Prd V06 Architecture Design

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

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

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]

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

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

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