architecture-patterns

What this skill does

# Architecture Patterns

## Overview

Architecture exists to support functionality. Every architectural decision should trace back to a functionality requirement.

**Core principle:** Design architecture FROM functionality, not TO functionality.

This skill is advisory in v10. It frames decisions and tradeoffs; it does not outrank explicit user requirements, repo standards, or an approved plan/design doc.

## Focus Areas (Reference Pattern)

- **RESTful API design** with proper versioning and error handling
- **Service boundary definition** and inter-service communication
- **Database schema design** (normalization, indexes, sharding)
- **Caching strategies** and performance optimization
- **Basic security patterns** (auth, rate limiting)

## The Iron Law

```
NO ARCHITECTURE DESIGN BEFORE FUNCTIONALITY FLOWS ARE MAPPED
```

If you haven't documented user flows, admin flows, and system flows, you cannot design architecture.

## Intake Routing

**First, determine what kind of architectural work is needed:**

| Request Type | Route To |
|--------------|----------|
| "Design API endpoints" | API Design section |
| "Plan system architecture" | Full Architecture Design |
| "Design data models" | Data Model section |
| "Plan integrations" | Integration Patterns section |
| "Make decisions" | Decision Framework section |

## Universal Questions (Answer First)

**ALWAYS answer before designing:**

1. **What functionality are we building?** - User stories, not technical features
2. **Who are the actors?** - Users, admins, external systems
3. **What are the user flows?** - Step-by-step user actions
4. **What are the system flows?** - Internal processing steps
5. **What integrations exist?** - External dependencies
6. **What are the constraints?** - Performance, security, compliance
7. **What observability is needed?** - Logging, metrics, monitoring, alerting

## Functionality-First Design Process

### Phase 1: Map Functionality Flows

**Before any architecture:**

```
User Flow (example):
1. User opens upload page
2. User selects file
3. System validates file type/size
4. System uploads to storage
5. System shows success message

Admin Flow (example):
1. Admin opens dashboard
2. Admin views all uploads
3. Admin can delete uploads
4. System logs admin action

System Flow (example):
1. Request received at API
2. Auth middleware validates token
3. Service processes request
4. Database stores data
5. Response returned
```

### Phase 2: Map to Architecture

**Each flow maps to components:**

| Flow Step | Architecture Component |
|-----------|----------------------|
| User opens page | Frontend route + component |
| User submits data | API endpoint |
| System validates | Validation service |
| System processes | Business logic service |
| System stores | Database + repository |
| System integrates | External client/adapter |

### Phase 3: Design Components

**For each component, define:**

- **Purpose**: What functionality it supports
- **Inputs**: What data it receives
- **Outputs**: What data it returns
- **Dependencies**: What it needs
- **Error handling**: What can fail

## Architecture Views

### System Context (C4 Level 1)
```
┌─────────────────────────────────────────────┐
│                 SYSTEM                       │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐     │
│  │   Web   │  │   API   │  │Database │     │
│  │   App   │──│ Service │──│         │     │
│  └─────────┘  └─────────┘  └─────────┘     │
└─────────────────────────────────────────────┘
       │              │              │
    ┌──┴──┐        ┌──┴──┐        ┌──┴──┐
    │User │        │Admin│        │ Ext │
    └─────┘        └─────┘        └─────┘
```

### Container View (C4 Level 2)
- **Web App**: React/Vue/Angular frontend
- **API Service**: REST/GraphQL backend
- **Database**: PostgreSQL/MongoDB/etc
- **Cache**: Redis/Memcached
- **Queue**: RabbitMQ/SQS for async

### Component View (C4 Level 3)
- **Controllers**: Handle HTTP requests
- **Services**: Business logic
- **Repositories**: Data access
- **Clients**: External integrations
- **Models**: Data structures

## LSP-Powered Architecture Analysis

**Use LSP to map actual code dependencies:**

| Architecture Task | LSP Tool | Output |
|-------------------|----------|--------|
| Map component dependencies | `lspCallHierarchy(outgoing)` | What each component uses |
| Find all consumers of a service | `lspCallHierarchy(incoming)` | Impact analysis |
| Verify interface implementations | `lspFindReferences` | All implementers |
| Trace data flow | Chain `lspCallHierarchy` calls | Full flow map |

**Mapping Actual Architecture:**
```
1. localSearchCode("ServiceName") → find entry points
2. lspCallHierarchy(outgoing) → map dependencies
3. For each dependency: repeat step 2
4. Build dependency graph from results
```

**Use LSP BEFORE drawing architecture diagrams** - verify assumptions with code.

**CRITICAL:** Always get lineHint from localSearchCode first. Never guess line numbers.

## API Design (Functionality-Aligned)

**Map user flows to endpoints:**

```
User Flow: Upload file
→ POST /api/files
  Request: { file: binary, metadata: {...} }
  Response: { id: string, url: string }
  Errors: 400 (invalid), 413 (too large), 500 (storage failed)

User Flow: View file
→ GET /api/files/:id
  Response: { id, url, metadata, createdAt }
  Errors: 404 (not found), 403 (not authorized)

Admin Flow: Delete file
→ DELETE /api/files/:id
  Response: { success: true }
  Errors: 404, 403
```

**API Design Checklist:**
- [ ] Each endpoint maps to a user/admin flow
- [ ] Request schema matches flow inputs
- [ ] Response schema matches flow outputs
- [ ] Errors cover all failure modes
- [ ] Auth/authz requirements documented

## Integration Patterns

**Map integration requirements to patterns:**

| Requirement | Pattern |
|-------------|---------|
| Flaky external service | Retry with exponential backoff |
| Slow external service | Circuit breaker + timeout |
| Async processing needed | Message queue |
| Real-time updates needed | WebSocket/SSE |
| Data sync needed | Event sourcing |

**For each integration:**
```markdown
### [Integration Name]

**Functionality**: What user flow depends on this?
**Pattern**: [Retry/Circuit breaker/Queue/etc]
**Error handling**: What happens when it fails?
**Fallback**: What's the degraded experience?
```

### Dependency Classification

Before choosing a pattern, classify the dependency:

| Category | Examples | Testing Strategy |
|----------|----------|-----------------|
| **In-process** | Pure computation, in-memory state | Test directly — merge modules and verify |
| **Local-substitutable** | Database (PGLite), filesystem (in-memory FS) | Test with local stand-in in test suite |
| **Remote but owned** | Your own microservices, internal APIs | Define port (interface), inject transport. Test with in-memory adapter |
| **True external** | Stripe, Twilio, third-party APIs | Mock at boundary. Inject dependency as port |

The category determines the pattern. In-process needs nothing. True external needs mocks. The middle two need ports and adapters.

**Implementation ordering — build from leaves inward:**
```
Level 0 (no deps):      [Pure utils] [Config]
        ↓
Level 1 (Level 0 only): [Repositories] [External clients]
        ↓
Level 2 (Level 0-1):    [Services]
        ↓
Level 3 (Level 0-2):    [Controllers] [API routes]
```
Level 0 components are testable immediately. Each subsequent level depends only on predecessors. This ordering eliminates mock-heavy tests in early phases and matches the planner's DAG constraint (phases depend only on predecessors, never on future phases).

## Observability Design

**For each component, define:**

| Aspect | Questions |
|--------|-----------|
| **Logging** | What events? What level? Structured format? |
| **Metrics** | What to measure? Counters, gauges, histograms? |
| **Alerts** | What thresholds? Who gets notified? |
| **Tracing** | Span boundaries? Correlation IDs? |

**Minimum obse