Architecture Design

Position in workflow: v0.5 Technical Stack Selection → v0.6 Architecture Design → v0.6 Technical Specification

Architecture defines how your system components connect. This skill transforms stack selections into a coherent system design with explicit boundaries and integration patterns.

Consumes

This skill requires prior work from v0.3-v0.5:

• **TECH-\* technology decisions** (from v0.5 Technical Stack Selection) — Tech choices become components; Build items become internal services, Buy/Integrate items become external connections
• **RISK-\* risk entries** (from v0.5 Risk Discovery Interview) — High-priority RISK-* entries must have architectural mitigations; drives design decisions on failover, security, scaling
• **FEA-\* feature entries** (from v0.3 Features Value Planning) — Features determine what components must be built; complex features may require distributed patterns
• **ARC-\* existing architecture decisions** (from prior products if brownfield) — Inherited patterns constrain new designs (monolith with microservice, library reuse, auth pattern, etc.)

This skill assumes v0.5 Technical Stack Selection is complete with TECH- entries providing technology foundations.

Produces

This skill creates/updates:

• **ARC-\* entries** (architecture decisions, status-based) — Decisions for structure, integration, security, performance, data, DevOps with rationale, alternatives considered, and consequences. No confidence scores; decisions have Status: Proposed/Accepted/Superseded
• System boundary diagram — Visual representation showing trust boundaries, components, and external integrations
• RISK-to-Architecture mapping — Validation showing every high-priority RISK- has corresponding ARC- mitigation or explicit acceptance
• Conformance rules (on ARC- entries) — for any decision that makes a structural claim ("X must not depend on Y", "all Z go through one adapter"), a machine-checkable rule. This turns the architecture into the expected topology (the blueprint graph) the v0.7 build is diffed against, and feeds the architectureconformance readiness dimension. See docs/DEVELOPMENTGRAPH.md.

All ARC- entries should include:

• Category: Structure/Integration/Security/Performance/Data/DevOps
• Context: What prompted this decision (derived from TECH-/RISK-/FEA- inputs)
• Decision: What was chosen
• Rationale: Why (not just what)
• Alternatives Rejected: Options considered and why not chosen
• Consequences: What this enables and constrains
• Related IDs: TECH-XXX, RISK-XXX, FEA-XXX references

Example ARC- entry (Structure):

ARC-001: Monolith with Module Boundaries
Category: Structure
Context: Team of 2 developers; unclear domain boundaries at v0.6; TECH-001 (Next.js) supports monolith pattern
Decision: Single Next.js application with domain-based module folders (auth/, reports/, data-sources/), clear module interfaces

Rationale:
  - TECH-001 (Next.js) designed for monoliths
  - Avoids ops complexity of microservices
  - Can extract services later when scaling needs emerge
  - Enables fast iteration for MVP

Alternatives Rejected:
  - Microservices: Premature (team too small); adds ops burden
  - Serverless: Harder to share code; cold start latency concerns (impacts UJ-001 response time)
  - Layered monolith: Less clear boundaries; module pattern better for future extraction

Consequences:
  - Enables: Fast iteration, simple deployment, shared state across domains
  - Constrains: Single scaling unit (can't scale auth independently); must be disciplined about module boundaries

Related IDs: TECH-001 (Next.js), RISK-005 (scaling concerns), FEA-001..FEA-020 (all features in one deployment)
Status: Accepted

Example ARC- entry (Security, addressing RISK-):

ARC-005: JWT with HTTP-Only Cookies
Category: Security
Context: Need session management for authenticated users; RISK-008 (security compliance) and TECH-003 (Clerk auth) guide this
Decision: JWTs stored in HTTP-only cookies, 1-hour expiry, refresh via /refresh endpoint

Rationale:
  - HTTP-only prevents XSS token theft (mitigates RISK-008 surface area)
  - Short expiry limits damage window if token stolen
  - Refresh flow handles long sessions gracefully
  - TECH-003 (Clerk) handles token lifecycle, we just enforce storage pattern

Alternatives Rejected:
  - localStorage: Vulnerable to XSS (RISK-008 violation)
  - Long-lived tokens: Increases risk exposure time (RISK-008)
  - Server sessions: Scaling complexity; would require Redis (not in TECH-)

Consequences:
  - Enables: Stateless auth, horizontal scaling
  - Constrains: Must handle refresh flow in frontend; logout requires token invalidation

Related IDs: TECH-003 (Clerk handles token generation), RISK-008 (security compliance), BR-010 (auth requirements)
Status: Accepted

Architecture Decision Categories

Design Process

1. Pull TECH- decisions — What technologies are we building with?
2. Pull RISK- constraints — What must the architecture account for?
3. Pull FEA- features — What must the system do?
4. Define system boundaries — What's in/out of scope?
5. Map component relationships — How do parts connect?
6. Document integration patterns — How do Buy/Integrate items connect?
7. Create ARC- entries — Record decisions with rationale

System Boundary Definition

Before designing components, define what's inside and outside your system:

Inside (Build):

• Core business logic
• Differentiating features
• Custom workflows

Outside (Buy/Integrate):

• Authentication provider
• Payment processor
• Email service
• Analytics

Boundary Questions:

• Where does data enter the system?
• Where does data leave the system?
• What trust boundaries exist?
• What must be fast vs. can be eventual?

Component Relationship Patterns

For Build Components

Rule for MVP: Start monolith, extract services when you have evidence of need.

For Buy/Integrate Components

Integration Architecture Patterns

Pattern: Vendor Abstraction

When you Buy a service but want flexibility to switch:

┌─────────────────────────────────────┐
│           Your Application          │
├─────────────────────────────────────┤
│       Payment Abstraction Layer     │
│   interface PaymentProvider {       │
│     charge(amount, token): Result   │
│   }                                 │
├─────────────────────────────────────┤
│  StripeAdapter  │  PaddleAdapter    │
└─────────────────┴───────────────────┘

When to use: High switching cost, multiple viable providers, strategic flexibility needed.

Pattern: Webhook Handler

When integrating with external events:

External Service → Webhook Endpoint → Event Queue → Handler
                        ↓
                   Signature Verify
                        ↓
                   Idempotency Check
                        ↓
                   Enqueue for processing

When to use: External services push events (Stripe, GitHub, etc.).

ARC- Output Template

ARC-XXX: [Decision Title]
Category: [Structure | Integration | Security | Performance | Data | DevOps]
Context: [What prompted this decision]
Decision: [What we decided]
Rationale: [Why this choice]

Alternatives Rejected:
  - [Option A]: [Why not]
  - [Option B]: [Why not]

Consequences:
  - Enables: [What this makes possible]
  - Constrains: [What this limits]

Conformance Rule (optional — for structural claims):
  - Rule: [e.g. "engine/ must not import the UI framework"]
  - Check: [type · scope · target, e.g. forbidden_import · engine/** · vscode]
  (verified against the as-built code in v0.7 → architecture_conformance; see docs/DEVELOPMENT_GRAPH.md)

Related IDs: [TECH-XXX, RISK-XXX, FEA-XXX]
Status: [Proposed | Accepted | Superseded]

Example ARC- entry:

ARC-001: Monolith with Module Boundaries
Category: Structure
Context: Need to choose application structure for MVP launch
Decision: Single Next.js application with domain-based module folders

Rationale:
  - Team of 2 developers, single deployment simplifies ops
  - Unclear domain boundaries at this stage
  - Can extract services later when patterns emerge

Alternatives Rejected:
  - Microservices: Premature; adds ops complexity without proven need
  - Serverless functions: Harder to share code, cold start concerns

Consequences:
  - Enables: Fast iteration, simple deployment, shared state
  - Constrains: Single scaling unit, must be disciplined about module boundaries

Related IDs: TECH-001 (Next.js), RISK-005 (scaling concerns)
Status: Accepted

Example ARC- entry (Security):

ARC-005: JWT with HTTP-Only Cookies
Category: Security
Context: Need session management strategy for authenticated users
Decision: JWTs stored in HTTP-only cookies, 1-hour expiry, refresh via /refresh endpoint

Rationale:
  - HTTP-only prevents XSS access to tokens
  - Short expiry limits damage from stolen tokens
  - Refresh flow handles long sessions gracefully

Alternatives Rejected:
  - localStorage: Vulnerable to XSS
  - Long-lived tokens: Security risk if compromised
  - Server-side sessions: Scaling complexity, Redis dependency

Consequences:
  - Enables: Stateless auth, horizontal scaling
  - Constrains: Must handle refresh flow in frontend, logout requires invalidation strategy

Related IDs: TECH-001 (Clerk handles this), RISK-008 (security compliance)
Status: Accepted

System Diagram Elements

When creating architecture diagrams, include:

Example Diagram Structure

┌─────────────────────────────────────────────────────────┐
│                    TRUST BOUNDARY                        │
│  ┌─────────────┐     ┌─────────────┐    ┌────────────┐  │
│  │   Frontend  │────▶│   API       │───▶│  Database  │  │
│  │   (Next.js) │     │  (tRPC)     │    │  (Supabase)│  │
│  └─────────────┘     └──────┬──────┘    └────────────┘  │
│                             │                            │
└─────────────────────────────┼────────────────────────────┘
                              │
              ┌───────────────┼───────────────┐
              ▼               ▼               ▼
        ┌──────────┐   ┌──────────┐   ┌──────────┐
        │  Stripe  │   │  Clerk   │   │  Resend  │
        │ (payments)│  │  (auth)  │   │ (email)  │
        └──────────┘   └──────────┘   └──────────┘
                    EXTERNAL SERVICES

RISK- to Architecture Mapping

Every high-priority risk should have an architectural response:

Anti-Patterns to Avoid

Quality Gates

Before proceeding to Technical Specification:

• All TECH- Build items have component placement
• All TECH- Buy/Integrate items have integration pattern
• High-priority RISK- entries have architectural mitigation
• Trust boundaries clearly defined
• Data flow documented
• ARC- entries created for major decisions

Downstream Connections

ARC- entries feed into:

Detailed References

• Architecture pattern examples: See references/examples.md
• ARC- entry template: See assets/arc.md
• Diagram templates: See references/diagrams.md