Skip to content

mattgierhart/PRD-driven-context-engineering / .claude/skills/prd-v06-architecture-design

prd-v06-architecture-design

Verified

Define how system components connect, establishing boundaries, patterns, and integration approaches during PRD v0.6 Architecture. Triggers on requests to design architecture, create system design, define component relationships, or when user asks "design architecture", "system design", "how do components connect?", "architecture decisions", "technical architecture", "system overview". Consumes TECH- (stack selections), RISK- (constraints), FEA- (features). Outputs ARC- entries documenting architecture decisions with rationale. Feeds v0.6 Technical Specification.

FileKindSize
SKILL.mdskill md15.8 KB
assets/arc.mdmarkdown1.5 KB
references/diagrams.mdmarkdown11.5 KB
references/examples.mdmarkdown7.7 KB

references/examples.md

View on GitHub
# Architecture Design Examples

## Example: Complete MVP Architecture

### Context
B2B SaaS dashboard for marketing analytics. Team of 2. MVP target: 100 users.

### Architecture Decisions

```
ARC-001: Monolith with Module Boundaries
Category: Structure
Context: Choosing application structure for MVP
Decision: Single Next.js app with /modules folder structure

Rationale:
  - Small team, single deployment reduces ops burden
  - Domain boundaries unclear until real usage
  - Can extract to services later with evidence

Alternatives Rejected:
  - Microservices: Premature complexity
  - Serverless-first: Cold starts problematic for dashboard

Consequences:
  - Enables: Fast iteration, simple deployment
  - Constrains: Single scaling unit

Related IDs: TECH-001
Status: Accepted
```

```
ARC-002: tRPC for Internal API
Category: Structure
Context: Need type-safe communication between frontend and backend
Decision: Use tRPC with Zod validation

Rationale:
  - End-to-end type safety catches errors at compile time
  - No API client generation needed
  - Works seamlessly with Next.js app router

Alternatives Rejected:
  - REST: Requires manual type definitions
  - GraphQL: Overkill for internal API, adds complexity

Consequences:
  - Enables: Type-safe API calls, great DX
  - Constrains: Not suitable for public API (use REST for that)

Related IDs: TECH-001, TECH-002
Status: Accepted
```

```
ARC-003: Supabase for Auth + Database
Category: Integration
Context: Need managed auth and database with real-time capabilities
Decision: Use Supabase for both auth and primary database

Rationale:
  - Integrated auth reduces complexity
  - Real-time subscriptions for dashboard updates
  - Postgres gives flexibility for analytics queries
  - Row-level security for multi-tenant data

Alternatives Rejected:
  - Separate auth (Clerk) + DB: More moving parts
  - Firebase: Firestore query limitations for analytics

Consequences:
  - Enables: Integrated auth/db, real-time, RLS
  - Constrains: Supabase-specific patterns (RLS policies)

Related IDs: TECH-002, TECH-003, RISK-001
Status: Accepted
```

```
ARC-004: Stripe with Webhook Handler
Category: Integration
Context: Need payment processing with subscription management
Decision: Stripe Checkout + Customer Portal, webhooks for sync

Rationale:
  - Stripe Checkout handles PCI compliance
  - Customer Portal reduces our UI work
  - Webhooks ensure data consistency

Pattern:
  Stripe Webhook → /api/webhooks/stripe → Verify signature → Enqueue → Process

Alternatives Rejected:
  - Build custom checkout: PCI compliance burden
  - Paddle: Less flexible, fewer payment methods

Consequences:
  - Enables: Reliable payments, less custom code
  - Constrains: Must handle webhook idempotency

Related IDs: TECH-004, FEA-020
Status: Accepted
```

### System Diagram

```
┌──────────────────────────────────────────────────────────────┐
│                     TRUST BOUNDARY                            │
│                                                               │
│  ┌────────────────────────────────────────────────────────┐  │
│  │                    Next.js App                          │  │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌────────┐  │  │
│  │  │  Pages   │  │  tRPC    │  │ Modules  │  │ Cron   │  │  │
│  │  │ (React)  │─▶│  Router  │─▶│ /reports │  │ Jobs   │  │  │
│  │  └──────────┘  └──────────┘  │ /data    │  └────────┘  │  │
│  │                              │ /billing │              │  │
│  │                              └──────────┘              │  │
│  └───────────────────────┬────────────────────────────────┘  │
│                          │                                    │
│  ┌───────────────────────▼────────────────────────────────┐  │
│  │                    Supabase                             │  │
│  │   ┌──────────┐  ┌──────────┐  ┌──────────┐             │  │
│  │   │   Auth   │  │ Postgres │  │ Real-time│             │  │
│  │   └──────────┘  └──────────┘  └──────────┘             │  │
│  └─────────────────────────────────────────────────────────┘  │
│                                                               │
└───────────────────────────────────────────────────────────────┘
                              │
          ┌───────────────────┼───────────────────┐
          ▼                   ▼                   ▼
    ┌──────────┐        ┌──────────┐        ┌──────────┐
    │  Stripe  │        │  Resend  │        │ PostHog  │
    │(payments)│        │ (email)  │        │(analytics│
    └──────────┘        └──────────┘        └──────────┘
                  EXTERNAL SERVICES
```

---

## Example: Risk-Driven Architecture Decision

```
ARC-010: Circuit Breaker for External APIs
Category: Performance
Context: RISK-001 identified API dependency outage as high-impact risk
Decision: Implement circuit breaker pattern for all external API calls

Rationale:
  - Prevents cascade failures when external service is down
  - Allows graceful degradation (show cached data, disable features)
  - Fast fail instead of timeout accumulation

Pattern:
  API Call → Circuit Breaker → External Service
       ↓ (if open)
  Fallback Response (cached data or feature disable)

Implementation:
  - Use opossum library for circuit breaker
  - Open circuit after 5 consecutive failures
  - Half-open retry after 30 seconds
  - Log all circuit state changes

Alternatives Rejected:
  - Simple retry: Doesn't prevent cascade failure
  - No protection: Unacceptable given RISK-001 severity

Consequences:
  - Enables: Graceful degradation, faster failure detection
  - Constrains: Must define fallback behavior for each integration

Related IDs: RISK-001, TECH-003, TECH-004
Status: Accepted
```

---

## Anti-Pattern Example: Architecture Astronaut

**Bad:**
```
ARC-001: Kubernetes with Service Mesh
Context: MVP for 100 users
Decision: Deploy on Kubernetes with Istio service mesh

Rationale: We might need to scale
```

**Why it's bad:**
- 100 users doesn't need Kubernetes
- Istio adds massive ops complexity
- "Might need" is not evidence

**Better:**
```
ARC-001: Single Vercel Deployment
Context: MVP for 100 users
Decision: Deploy as single Vercel app

Rationale:
  - Zero ops burden for small team
  - Auto-scaling handles 100-10K users
  - Can migrate to containers when we have evidence of need

Revisit trigger: >10K DAU or complex background job needs
```
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall