Target Architecture

Design a target (to-be) architecture that systematically addresses every gap and risk identified in the gap analysis while preserving the working parts of the existing system. This skill produces an evidence-backed architecture proposal with migration deltas, technology decisions, component diagrams, and interface contracts.

When to Use This Skill

• After completing Architecture Gap Analysis to design the desired end-state
• When stakeholders need a concrete architecture proposal to evaluate
• When planning a major refactor or system modernization
• As input to Migration Strategy (how to get from as-is to to-be)
• When evaluating technology choices for system evolution

Pipeline Position

[ARCH_GAPS_AND_RISKS.md + AS_IS_SYSTEM_MODEL.md + Codebase] --> **TARGET ARCHITECTURE** --> [TO_BE_ARCHITECTURE.md] --> Migration Strategy --> ...

Input: ARCH_GAPS_AND_RISKS.md, AS_IS_SYSTEM_MODEL.md, actual codebase (for verification) Output: TO_BE_ARCHITECTURE.md written to artifacts directory

Artifact Template

The output artifact follows the standard artifact template:

# [ARTIFACT TITLE]
## Summary
## Inputs
## Outputs
## Assumptions
## Open Questions
## Main Content
## Acceptance Criteria

Process

Step 1: Read Upstream Artifacts

1. Read ARCH_GAPS_AND_RISKS.md to understand:
   • Gap inventory (GAP-NNNN) with priorities and categories
   • Risk registry (RISK-NNNN) with severities and mitigations
   • Technical debt summary and hotspot analysis
   • Recommended actions from each gap/risk entry
2. Read AS_IS_SYSTEM_MODEL.md to understand:
   • Current component inventory (COMP-NNNN)
   • Current technology stack
   • Current dependency map
   • Current data flow
3. Build a resolution checklist: For every GAP and RISK, note whether the target architecture must address it directly, mitigate it, or accept it

Step 2: Define Architecture Principles

Establish guiding principles for the target architecture design.

1. Extract principles from gap analysis: Each category of gaps implies a principle

   • Architecture gaps -> Separation of concerns, modularity
   • Security gaps -> Defense in depth, least privilege
   • Performance gaps -> Efficient resource usage, caching strategy
   • Maintainability gaps -> Single responsibility, consistent patterns
   • Reliability gaps -> Fault tolerance, graceful degradation
   • Observability gaps -> Visibility, traceability

2. Assign PRINC-NNNN IDs: Sort alphabetically by principle title, assign sequentially

3. Principle format:

### PRINC-0001: [Title]
- **Category**: Architecture | Security | Performance | Maintainability | Reliability | Observability
- **Statement**: [One-sentence principle]
- **Rationale**: [Why this principle matters, citing gaps that motivate it]
- **Addresses**: [GAP-NNNN, RISK-NNNN list]

Step 3: Design Target Component Architecture

Define the desired component structure.

1. Retain components that work well (no associated gaps/risks or only P2 issues)

2. Refactor components that have P1 gaps (improve but preserve)

3. Replace components that have P0 gaps or critical risks (redesign)

4. Add new components that are missing from the as-is state (e.g., missing middleware layer, missing caching layer)

5. For each target component, record:

### TCOMP-0001: [Name]
- **Origin**: Retained from COMP-NNNN | Refactored from COMP-NNNN | New
- **Type**: Service | Library | Module | Package | Worker | CLI | UI | Middleware | Gateway
- **Responsibility**: [Single-sentence description of what this component does]
- **Interfaces**:
  - **Inbound**: [What it accepts and from whom]
  - **Outbound**: [What it produces and for whom]
- **Technology**: [Language, framework, key libraries]
- **Addresses**: [GAP-NNNN, RISK-NNNN list that this component resolves]
- **Design Notes**: [Key design decisions for this component]

6. Assign TCOMP-NNNN IDs: Sort alphabetically by component name, assign sequentially

Step 4: Build Migration Delta Table

Create a comprehensive comparison of as-is vs to-be states.

1. For each as-is component (COMP-NNNN), map to target state:

| AS-IS (COMP) | TO-BE (TCOMP) | Change Type | Rationale | Gaps Addressed |
|-------------|--------------|-------------|-----------|----------------|
| COMP-0001: API Server | TCOMP-0002: API Gateway | Refactor | Add middleware layer, rate limiting | GAP-0003, GAP-0007 |
| COMP-0003: DB Direct | TCOMP-0004: Data Access Layer | Replace | Abstract database access, add repository pattern | GAP-0001, RISK-0002 |
| (none) | TCOMP-0005: Cache Layer | Add | No caching exists; needed for performance | GAP-0012 |
| COMP-0006: Legacy Auth | (removed) | Remove | Replaced by TCOMP-0003 | GAP-0005, RISK-0001 |

2. Change types:
   • Retain: No changes needed; component is sound
   • Refactor: Internal changes but same external interface
   • Replace: New implementation with different interface
   • Add: New component not present in as-is
   • Remove: Component eliminated (functionality moved or deprecated)
   • Merge: Multiple as-is components combined into one
   • Split: One as-is component divided into multiple

Step 5: Make Technology Decisions

Document technology choices with alternatives considered.

1. For each significant technology decision, record:

### TDEC-0001: [Decision Title]
- **Category**: Language | Framework | Database | Infrastructure | Library | Pattern
- **Decision**: [What was chosen]
- **Alternatives Considered**:
  | Alternative | Pros | Cons | Rejected Because |
  |------------|------|------|-----------------|
  | [Option A] | [Pros] | [Cons] | [Reason] |
  | [Option B] | [Pros] | [Cons] | [Reason] |
- **Rationale**: [Why this choice best addresses the gaps/risks]
- **Trade-offs**: [What this decision gives up]
- **Addresses**: [GAP-NNNN, RISK-NNNN list]
- **Constraints**: [CON-NNNN from review brief that influenced this decision]
- **Reversibility**: High | Medium | Low

2. Assign TDEC-NNNN IDs: Sort alphabetically by decision title, assign sequentially

3. Decision criteria:

   • Does it address the identified gaps/risks?
   • Does it respect constraints from the review brief (CON-NNNN)?
   • Does it minimize migration risk?
   • Does the team have or can acquire the skills?
   • Does it avoid introducing new categories of risk?

Step 6: Define Interface Contracts

Specify the interfaces between target components.

1. For each component boundary, define:

### IFACE-0001: [Component A] -> [Component B]
- **Protocol**: HTTP/REST | gRPC | Message Queue | Function Call | Event Bus
- **Data Format**: JSON | Protobuf | Avro | Plain Text
- **Authentication**: [How the caller authenticates]
- **Key Operations**:
  | Operation | Method/Action | Input | Output | Error Cases |
  |-----------|--------------|-------|--------|-------------|
  | Create User | POST /users | UserCreateDTO | UserResponseDTO | 400, 409, 500 |
- **SLA**: [Latency, throughput, availability expectations]
- **Contract Evolution**: [Versioning strategy]

2. Assign IFACE-NNNN IDs: Sort by source component TCOMP ID, then by target component TCOMP ID

3. Data format specifications:

   • For key DTOs/messages, provide schema outlines
   • Specify required vs optional fields
   • Note backward compatibility requirements

Step 7: Create Target Architecture Diagrams

Produce Mermaid diagrams showing the target state.

1. Component Diagram (high-level):

```mermaid
graph TD
    subgraph External
        Client[Client Applications]
        ExtAPI[External APIs]
    end
    subgraph Target System
        GW[TCOMP-0001: API Gateway]
        Auth[TCOMP-0002: Auth Service]
        Core[TCOMP-0003: Core Service]
        Data[TCOMP-0004: Data Layer]
        Cache[TCOMP-0005: Cache]
        Queue[TCOMP-0006: Message Queue]
        Worker[TCOMP-0007: Worker]
    end
    subgraph Data Stores
        DB[(Database)]
        ObjStore[(Object Storage)]
    end
    Client --> GW
    GW --> Auth
    GW --> Core
    Core --> Data
    Core --> Cache
    Core --> Queue
    Queue --> Worker
    Data --> DB
    Worker --> ObjStore
    Core --> ExtAPI

2. **Data Flow Diagram** (for primary path):
```markdown
```mermaid
flowchart LR
    Request -->|HTTPS| Gateway
    Gateway -->|Validate| Auth
    Auth -->|Token| Gateway
    Gateway -->|Route| Service
    Service -->|Check| Cache
    Cache -.->|Miss| DB[(Database)]
    Service -->|Response| Gateway
    Gateway -->|HTTPS| Response

3. **Deployment Diagram** (if infrastructure changes proposed):
   - Container/pod layout
   - Network boundaries
   - Load balancer placement

### Step 8: Map Gap/Risk Resolution

Create an explicit mapping showing how each gap and risk is addressed.

1. **Resolution table**:
```markdown
| Gap/Risk ID | Title | Resolution Strategy | Target Component | Status |
|------------|-------|-------------------|-----------------|--------|
| GAP-0001 | Missing data abstraction | TCOMP-0004 introduces repository pattern | TCOMP-0004 | Resolved |
| GAP-0005 | Hardcoded secrets | TCOMP-0002 + vault integration | TCOMP-0002 | Resolved |
| RISK-0003 | Database single point of failure | Accepted risk with monitoring | N/A | Accepted |

2. Resolution statuses:

   • Resolved: Target architecture directly addresses this
   • Mitigated: Risk reduced but not eliminated
   • Accepted: Consciously accepted with documented rationale
   • Deferred: Will be addressed in a future phase

3. Verify completeness: Every GAP-NNNN and RISK-NNNN from the gap analysis must appear in this table

Step 9: Compile Target Architecture Artifact

Assemble all findings into the final artifact.

1. Write TO_BE_ARCHITECTURE.md following the template
2. Verify all gaps and risks are mapped to resolution strategies
3. Verify component diagrams include all TCOMP-NNNN entries
4. Verify interface contracts cover all component boundaries
5. Cross-reference with upstream artifact IDs

Output Format

TO_BE_ARCHITECTURE.md Structure

# Target Architecture: [Project Name]

## Summary
[3-5 sentence overview: architecture vision, key changes from as-is, number of components, major technology decisions]

## Inputs
- ARCH_GAPS_AND_RISKS.md
- AS_IS_SYSTEM_MODEL.md
- Codebase at: [path]

## Outputs
- TO_BE_ARCHITECTURE.md (this document)

## Assumptions
- [ASM-NNNN]: [Assumption with rationale]

## Open Questions
- [OQ-NNNN]: [Architecture questions requiring stakeholder input]

## Main Content

### Architecture Principles
[PRINC-NNNN entries]

### Target Component Architecture
[TCOMP-NNNN entries with full detail]

#### Component Diagram
```mermaid
[Target component diagram]

Migration Delta

AS-IS	TO-BE	Change Type	Rationale	Gaps Addressed

Technology Decisions

[TDEC-NNNN entries with alternatives]

Interface Contracts

[IFACE-NNNN entries with operation tables]

Data Flow

[Target data flow diagram]

Gap/Risk Resolution Map

ID	Title	Strategy	Target Component	Status

Unresolved Items

[Items with status Accepted or Deferred, with rationale]

Acceptance Criteria

• Every GAP-NNNN from gap analysis appears in resolution map
• Every RISK-NNNN from gap analysis appears in resolution map
• All TCOMP-NNNN appear in component diagram
• Technology decisions document alternatives considered
• Interface contracts specify data formats and error cases
• Migration delta covers every COMP-NNNN from as-is model
• Architecture principles trace to specific gaps
• Mermaid diagrams render correctly

**Output path**: `artifacts/brownfield/<project_name>/TO_BE_ARCHITECTURE.md`

**Template**: `${CLAUDE_PLUGIN_ROOT}/reference/templates/TO_BE_ARCHITECTURE.template.md`

## Determinism Rules

These rules ensure reproducible output regardless of when or how many times the skill is invoked on the same inputs.

1. **TCOMP-NNNN IDs**: Sort all target components alphabetically by name (case-insensitive), assign sequentially starting at 0001
2. **PRINC-NNNN IDs**: Sort all principles alphabetically by title, assign sequentially starting at 0001
3. **TDEC-NNNN IDs**: Sort all technology decisions alphabetically by title, assign sequentially starting at 0001
4. **IFACE-NNNN IDs**: Sort by source TCOMP ID, then by target TCOMP ID, assign sequentially starting at 0001
5. **Migration delta rows**: Sort by AS-IS COMP-NNNN ID numerically; new components (Add) sorted alphabetically at the end
6. **Resolution map rows**: Sort by Gap/Risk ID (GAP first, then RISK, numerically within each)
7. **Alternatives table rows**: Sort alphabetically by alternative name
8. **Sections**: Always in template order, never reordered
9. **No timestamps**: Do not include generation timestamps in artifact body
10. **Diagram node IDs**: Use TCOMP-NNNN as node identifiers in Mermaid diagrams

## Evidence Citation Rules

Target architecture claims reference both upstream artifacts and codebase evidence.

**Format for upstream references**: `[ARTIFACT_NAME: ID]` (e.g., `[ARCH_GAPS: GAP-0003]`, `[AS_IS: COMP-0001]`)
**Format for codebase references**: `> Claim text [relative/path/to/file.ext:line_number]`

**Examples**:
```markdown
> Current API handler lacks input validation, motivating the Gateway component [src/routes/api.ts:15-30]
> This decision addresses the missing abstraction layer identified in [ARCH_GAPS: GAP-0001]
> The existing authentication module will be retained and enhanced [AS_IS: COMP-0002]

Rules:

• Technology decisions MUST cite the gaps/risks they address
• Component origins MUST cite the as-is component they derive from (or state "New")
• Resolution map entries MUST link to specific TCOMP-NNNN or TDEC-NNNN
• If a design decision is based on team/organizational constraints, cite the CON-NNNN from the review brief

Quality Checklist

Before finalizing the artifact, verify:

• Every GAP-NNNN from gap analysis has a resolution entry (Resolved, Mitigated, Accepted, or Deferred)
• Every RISK-NNNN from gap analysis has a resolution entry
• All TCOMP-NNNN components appear in the component diagram
• Migration delta table covers every COMP-NNNN from AS_IS_SYSTEM_MODEL.md
• Technology decisions include at least 2 alternatives considered per decision
• Interface contracts specify protocol, data format, and key operations
• Architecture principles trace to specific gaps that motivate them
• No circular dependencies in the target component diagram
• Accepted/Deferred items have documented rationale
• Mermaid diagrams use valid syntax and render correctly
• TCOMP-NNNN IDs sorted alphabetically by name
• TDEC-NNNN decisions note reversibility level
• Constraints from review brief (CON-NNNN) are respected in design

Error Handling

• ARCH_GAPS_AND_RISKS.md not found: Report error; direct user to run architecture-gap-analysis first
• AS_IS_SYSTEM_MODEL.md not found: Report error; direct user to run codebase-discovery-as-is first
• No gaps or risks found: Unusual but valid; target architecture matches as-is state. Document this explicitly and verify the gap analysis was thorough.
• Conflicting constraints: If constraints (CON-NNNN) conflict with gap resolution, document the conflict in Open Questions and propose compromise alternatives
• Team skill gaps: If proposed technology requires skills the team lacks, flag in Assumptions and increase migration timeline estimates
• Budget constraints: If architectural ideal exceeds budget, propose phased approach with minimum viable architecture first