Architecture Design

Transform FUNCTIONAL_SPEC.md and REQUIREMENTS.md artifacts into a comprehensive ARCHITECTURE.md artifact containing system overview, component diagrams, data flow sequences, technology stack recommendations, interface contracts, and scalability notes. This is the fourth step in the greenfield specification pipeline — it takes detailed feature specifications and produces a language-agnostic system design that guides implementation.

When to Use This Skill

• A FUNCTIONAL_SPEC.md exists and has been validated
• You need to define the system structure before task breakdown
• The team needs a shared understanding of components and their interactions
• Technology stack decisions need to be documented with rationale
• Scalability and deployment concerns need to be addressed

Pipeline Position

[Raw Idea] → [PROBLEM_BRIEF.md] → [REQUIREMENTS.md] → [FUNCTIONAL_SPEC.md] → **ARCHITECTURE** → [ARCHITECTURE.md] → Task Breakdown → ...

Input: artifacts/greenfield/<project_name>/FUNCTIONAL_SPEC.md, artifacts/greenfield/<project_name>/REQUIREMENTS.md Output: artifacts/greenfield/<project_name>/ARCHITECTURE.md

Core Principle: Language-Agnostic Design

This skill describes components and interfaces, not implementation details. The architecture document should be valid regardless of which programming language, framework, or cloud provider is chosen.

Do:

• Describe what each component does and what interfaces it exposes
• Define data flow between components using protocol-level descriptions
• Specify quality attributes (latency, throughput, availability) as constraints
• Document trade-offs and alternatives considered

Do not:

• Specify programming languages (say "API Gateway" not "Express.js server")
• Prescribe specific frameworks (say "ORM Layer" not "Prisma")
• Name specific cloud services (say "Object Storage" not "S3 Bucket")
• Include code snippets or configuration examples

Exception: The Technology Stack section may recommend specific technologies with rationale, but these are recommendations, not mandates. The component design must work with any reasonable alternative.

Process

Step 1: Read and Analyze Inputs

Load FUNCTIONAL_SPEC.md and REQUIREMENTS.md. Extract:

From FUNCTIONAL_SPEC.md:

• Feature specs (FS-NNNN) — each may map to one or more components
• Data models — define persistence requirements
• API contracts — define interface boundaries
• User flows — reveal interaction patterns
• Cross-cutting concerns — inform shared infrastructure

From REQUIREMENTS.md:

• NFRs — drive architecture decisions (performance, security, scalability, usability, reliability)
• Dependencies between REQs — may imply component dependencies
• Priority levels — P0 requirements drive the core architecture

Step 2: Identify Components

Decompose the system into logical components. Each component should have:

• A single, clear responsibility
• Well-defined interfaces (inputs/outputs)
• Independent deployability (where possible)
• Clear ownership boundary

Component types:

Type	Description	Examples
Presentation	User-facing interfaces	Web Client, Mobile Client, CLI
API	Interface between presentation and business logic	API Gateway, GraphQL Layer, REST API
Service	Core business logic and orchestration	User Service, Order Service, Notification Service
Data	Persistence and data management	Primary Database, Cache Layer, Search Index
Infrastructure	Cross-cutting platform concerns	Auth Provider, Message Queue, Object Storage
External	Third-party systems and integrations	Payment Provider, Email Service, Analytics

Component identification process:

1. Map each FS-NNNN to the component(s) that implement it
2. Identify shared functionality across features (becomes infrastructure components)
3. Identify external dependencies (becomes external components)
4. Verify each component has a clear boundary and interface
5. Check that no component has too many responsibilities (split if > 3 feature specs)

Step 3: Design Component Diagram

Create a Mermaid component diagram showing all components and their relationships:

graph TB
    subgraph Presentation
        WEB[Web Client]
        MOB[Mobile Client]
    end

    subgraph API Layer
        GW[API Gateway]
    end

    subgraph Services
        US[User Service]
        OS[Order Service]
        NS[Notification Service]
    end

    subgraph Data
        DB[(Primary Database)]
        CACHE[(Cache Layer)]
    end

    subgraph External
        PAY[Payment Provider]
        EMAIL[Email Service]
    end

    WEB --> GW
    MOB --> GW
    GW --> US
    GW --> OS
    OS --> PAY
    NS --> EMAIL
    US --> DB
    US --> CACHE
    OS --> DB

Diagram rules:

• Use subgraphs for component groups (Presentation, API, Services, Data, External)
• Arrows show direction of dependency (caller → callee)
• Label arrows with protocol/interface type where helpful
• Keep diagram to 15 components maximum (decompose further in separate diagrams if needed)
• External systems use different styling to distinguish from internal components

Step 4: Design Data Flow

Create Mermaid sequence diagrams for each major user flow from the functional spec:

sequenceDiagram
    actor User
    participant WEB as Web Client
    participant GW as API Gateway
    participant US as User Service
    participant DB as Database

    User->>WEB: Submit registration form
    WEB->>GW: POST /api/v1/users
    GW->>GW: Validate auth token
    GW->>US: Create user request
    US->>US: Validate business rules
    US->>DB: INSERT user record
    DB-->>US: User created (id: uuid)
    US-->>GW: 201 Created
    GW-->>WEB: User response
    WEB-->>User: Show success message

Data flow rules:

• Create one sequence diagram per P0 feature's happy path (minimum)
• Create error flow diagrams for critical failure modes
• Show all components involved in the flow
• Include validation and business rule steps
• Reference FS-NNNN, BR-NNNN, and API-NNNN IDs in diagram notes
• Keep diagrams to 10-15 interactions maximum

Step 5: Define Technology Stack

Recommend technologies for each component category with clear rationale:

Technology stack format:

Category: [Presentation | API | Service | Data | Infrastructure]
Component: [Component Name]
Recommendation: [Technology Name]
Rationale: [Why this technology fits the NFRs and constraints]
Alternatives Considered: [Other options and why they were not chosen]
Risk: [Any risks associated with this choice]

Selection criteria (in priority order):

1. NFR compliance (does it meet performance, security, scalability requirements?)
2. Constraint compliance (does it satisfy CON-NNNN from problem brief?)
3. Team capability (can the team realistically use this?)
4. Ecosystem maturity (is it production-ready with good documentation?)
5. Total cost of ownership (licensing, hosting, maintenance)

Step 6: Define Interfaces and Contracts

For each component-to-component connection, define the interface:

Interface format:

Interface: [Source Component] → [Target Component]
Protocol: [HTTP/REST | gRPC | GraphQL | WebSocket | Message Queue | Direct Call]
Authentication: [API Key | JWT | mTLS | None]
Data Format: [JSON | Protobuf | Avro]
SLA:
  - Latency: [p95 target]
  - Availability: [target %]
  - Throughput: [requests per second]
Error Handling: [Retry policy, circuit breaker, fallback]

Rules for interfaces:

• Every arrow in the component diagram must have a defined interface
• Synchronous interfaces (HTTP, gRPC) must specify timeout values
• Asynchronous interfaces (message queues) must specify delivery guarantees
• All interfaces must specify authentication mechanism
• Error handling must include retry policy and circuit breaker thresholds

Step 7: Document Scalability Considerations

Address how the system scales along key dimensions:

Scalability dimensions:

• User scale: How does the system handle 10x, 100x user growth?
• Data scale: How does the system handle growing data volumes?
• Geographic scale: How does the system serve users in multiple regions?
• Feature scale: How easily can new features be added?

For each dimension, document:

• Current design capacity
• Scaling strategy (horizontal vs. vertical, caching, sharding, CDN)
• Bottleneck components (what breaks first under load?)
• Migration path (what changes when scaling is needed?)

Output Format

Write the artifact following the template at ${CLAUDE_PLUGIN_ROOT}/reference/templates/ARCHITECTURE.template.md.

The artifact must follow the standard artifact template structure:

# ARCHITECTURE: [Project Name]

## Summary
[2-3 sentence summary: component count, architecture style, key design decisions]

## Inputs
- **Functional Spec**: `FUNCTIONAL_SPEC.md` — [FS count, data models, API contracts referenced]
- **Requirements**: `REQUIREMENTS.md` — [NFRs that drive architecture decisions]
- **Problem Brief**: `PROBLEM_BRIEF.md` — [Constraints referenced]

## Outputs
- This document (ARCHITECTURE.md)
- Feeds into: TASKS.md (via task-breakdown skill)
- Feeds into: IMPLEMENTATION_PLAN.md (via implementation-planning skill)

## Assumptions
- [ASM-0001]: [Architecture assumption — e.g., "Single-region deployment initially"]
- ...

## Open Questions
- [OQ-0001]: [Question that affects architecture — e.g., "Expected peak concurrent users?"]
- ...

## Main Content

### System Overview

[2-3 paragraphs describing the overall architecture approach: monolith vs. microservices vs. modular monolith, synchronous vs. asynchronous communication, deployment model, and key trade-offs made]

**Architecture Style**: [Monolith | Modular Monolith | Microservices | Serverless | Hybrid]
**Communication Pattern**: [Synchronous | Asynchronous | Event-Driven | Hybrid]
**Deployment Model**: [Single Server | Containerized | Orchestrated | Serverless]

### Component Diagram

```mermaid
graph TB
    subgraph Presentation
        ...
    end
    subgraph API Layer
        ...
    end
    subgraph Services
        ...
    end
    subgraph Data
        ...
    end
    subgraph External
        ...
    end

Component Catalog

ID	Component	Type	Responsibility	Implements	Dependencies
COMP-0001	[Name]	[Type]	[Single responsibility]	FS-0001, FS-0002	COMP-0003
COMP-0002	[Name]	[Type]	[Single responsibility]	FS-0003	COMP-0001
...	...	...	...	...	...

Data Flow Diagrams

Flow 1: [Primary User Flow Name] (FS-0001)

sequenceDiagram
    actor User
    participant C1 as [Component 1]
    participant C2 as [Component 2]
    participant DB as [Database]

    User->>C1: [Action]
    C1->>C2: [Request]
    C2->>DB: [Query]
    DB-->>C2: [Result]
    C2-->>C1: [Response]
    C1-->>User: [Output]

Notes:

• Step 2 validates BR-0001 from FS-0001
• Step 3 references data model [Entity Name]

Flow 2: [Error/Recovery Flow Name]

sequenceDiagram
    ...

[... additional flows for P0 features ...]

Technology Stack

Category	Component	Recommendation	Rationale	Alternatives
Presentation	Web Client	[Tech]	[Why]	[Alternatives]
API	API Gateway	[Tech]	[Why]	[Alternatives]
Service	Core Services	[Tech]	[Why]	[Alternatives]
Data	Primary Database	[Tech]	[Why]	[Alternatives]
Data	Cache	[Tech]	[Why]	[Alternatives]
Infrastructure	Auth	[Tech]	[Why]	[Alternatives]
Infrastructure	Hosting	[Tech]	[Why]	[Alternatives]

Interfaces and Contracts

[Source Component] → [Target Component]

• Protocol: [HTTP/REST | gRPC | WebSocket | Message Queue]
• Authentication: [JWT | API Key | mTLS | None]
• Data Format: [JSON | Protobuf]
• SLA:
  • Latency: [p95 target]
  • Availability: [target %]
  • Throughput: [RPS target]
• Error Handling: [Retry policy, circuit breaker config]
• Timeout: [Value in seconds]

[... additional interfaces ...]

Scalability Notes

User Scale

• Current Design Capacity: [N concurrent users]
• Scaling Strategy: [Horizontal scaling of service layer, read replicas for DB]
• Bottleneck: [Component that fails first under load]
• Migration Path: [What to change when scaling]

Data Scale

• Current Design Capacity: [N records / GB]
• Scaling Strategy: [Partitioning, archival, sharding]
• Bottleneck: [Table/collection that grows fastest]
• Migration Path: [What to change when data grows]

Geographic Scale

• Current Design: [Single region]
• Future Considerations: [CDN, multi-region deployment, data residency]

Feature Scale

• Extensibility Pattern: [Plugin architecture, feature flags, modular boundaries]
• Adding New Features: [Process for adding components without affecting existing ones]

Security Architecture

Authentication Flow

[How users authenticate — token-based, session-based, OAuth, etc.]

Authorization Model

[RBAC, ABAC, or custom — how permissions are evaluated]

Data Protection

[Encryption at rest, in transit, PII handling, key management]

Threat Model

[Top 3-5 threats and mitigations, referencing NFR-NNNN security requirements]

Deployment Architecture

graph TB
    subgraph Production
        LB[Load Balancer]
        APP1[App Instance 1]
        APP2[App Instance 2]
        DB[(Database Primary)]
        DBR[(Database Replica)]
    end

    LB --> APP1
    LB --> APP2
    APP1 --> DB
    APP2 --> DB
    DB --> DBR

Deployment strategy: [Blue-green | Rolling | Canary] CI/CD pipeline: [Build → Test → Stage → Production] Rollback strategy: [How to revert a bad deployment]

Acceptance Criteria

• Every FS-NNNN maps to at least one component (COMP-NNNN)
• Component diagram shows all components and their relationships
• Data flow diagrams exist for all P0 feature happy paths
• Technology stack recommendations include rationale and alternatives
• Every component-to-component connection has a defined interface
• Scalability notes address user, data, geographic, and feature dimensions
• Security architecture covers authentication, authorization, data protection
• Deployment architecture is documented with rollback strategy
• All Mermaid diagrams render correctly
• Design is language-agnostic (except Technology Stack recommendations)

**Output path**: `artifacts/greenfield/<project_name>/ARCHITECTURE.md`

## Determinism Rules

1. COMP-NNNN IDs: Sort alphabetically by component name, assign sequential 4-digit numbers starting from 0001
2. Components listed in order: Presentation, API, Service, Data, Infrastructure, External
3. Data flow diagrams ordered by FS-NNNN reference (lowest first)
4. Technology stack ordered by category: Presentation, API, Service, Data, Infrastructure
5. Interfaces ordered by source component COMP-NNNN, then target component COMP-NNNN
6. No timestamps in artifact body
7. Sections must appear in template order

## Architecture Decision Records

For significant design decisions, document the reasoning:

**Format:**

Decision: [What was decided] Context: [Why was this decision needed] Options Considered:

1. [Option A] — [Pros/Cons]
2. [Option B] — [Pros/Cons]
3. [Option C] — [Pros/Cons] Chosen: [Option X] Rationale: [Why Option X was selected] Consequences: [What this decision implies for the rest of the system]

Include ADRs for decisions such as:
- Monolith vs. microservices
- SQL vs. NoSQL
- Synchronous vs. asynchronous communication
- Authentication approach
- Deployment model

## Quality Checklist

Before completing, verify:
- [ ] Every FS-NNNN maps to at least one component
- [ ] No component has more than 3 feature specs (split if over)
- [ ] Component diagram is clear and renders correctly
- [ ] Data flow diagrams cover all P0 feature happy paths
- [ ] At least one error flow diagram exists
- [ ] Technology stack has rationale for every recommendation
- [ ] Every connection has a defined interface with SLA
- [ ] Scalability notes are realistic and actionable
- [ ] Security architecture addresses authentication, authorization, and data protection
- [ ] Deployment architecture includes rollback strategy
- [ ] Design is language-agnostic (except Technology Stack section)
- [ ] All Mermaid diagrams are syntactically valid
- [ ] NFR compliance is traceable (each NFR maps to a design decision)
- [ ] Architecture assumptions are documented
- [ ] Open questions are flagged for items that affect design

## Common Pitfalls

1. **Over-engineering for scale**: A system expected to serve 100 users does not need microservices and Kubernetes. Start simple, document the scaling path.
2. **Missing error flows**: Happy path architecture is incomplete. Document what happens when components fail, databases are unreachable, or external services are down.
3. **Prescribing implementation**: "Use Express.js with Prisma on AWS" is implementation. "HTTP API layer with ORM and cloud deployment" is architecture.
4. **Ignoring security**: Security is not an add-on. Authentication, authorization, and data protection must be in the core design.
5. **No deployment story**: Architecture without a deployment model is theoretical. Include how the system gets from code to production.
6. **Tight coupling**: If changing one component requires changing three others, the boundaries are wrong. Each component should be independently deployable.
7. **Missing external dependencies**: Third-party APIs, payment providers, email services — if the system depends on them, they must be in the architecture.
8. **Diagram-only architecture**: Diagrams without prose are ambiguous. Every diagram needs explanatory text that captures intent and trade-offs.