version: "1.0.1" name: architecture-patterns description: "Internal cc10x skill, injected by the router via SKILL_HINTS for multi-component, API, schema, auth, or integration-heavy work. Frames system and API design tradeoffs; advisory, never overrides user/repo/plan." allowed-tools: Read Grep Glob LSP user-invocable: false

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. 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:

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:

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:

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:

For each integration:

### [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:

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:

Minimum observability:

• Request/response logging at boundaries
• Error rates and latencies
• Health check endpoint
• Correlation ID propagation

Decision Framework

For each architectural decision:

### Decision: [Title]
 
**Context**: What functionality requirement drives this?
 
**Options**:
1.[Option A] - [Brief description]
2.[Option B] - [Brief description]
3.[Option C] - [Brief description]
 
**Trade-offs**:
| Criterion | Option A | Option B | Option C |
|-----------|----------|----------|----------|
| Performance | Good | Better | Best |
| Complexity | Low | Medium | High |
| Cost | Low | Medium | High |
 
**Decision**: [Option chosen]
 
**Rationale**: [Why this option best supports functionality]

Red Flags - STOP and Redesign

If you find yourself:

• Designing architecture before mapping flows
• Adding components without clear functionality
• Choosing patterns because "it's best practice"
• Over-engineering for hypothetical scale
• Ignoring existing architecture patterns
• Making decisions without documenting trade-offs

STOP. Go back to functionality flows.

Keep It Simple (Reference Pattern)

Approach for backend architecture:

1. Start with clear service boundaries
2. Design APIs contract-first
3. Consider data consistency requirements
4. Plan for horizontal scaling from day one
5. Keep it simple - avoid premature optimization

Architecture Output Checklist:

• [ ] API endpoint definitions with example requests/responses
• [ ] Service architecture diagram (mermaid or ASCII)
• [ ] Database schema with key relationships
• [ ] Technology recommendations with brief rationale
• [ ] Potential bottlenecks and scaling considerations

Always provide concrete examples. Focus on practical implementation over theory.

Rationalization Prevention

Output Format

# Architecture Design: [Feature/System Name]
 
## Functionality Summary
[What this architecture supports - trace to user value]
 
## Flows Mapped
 
### User Flows
1.[Flow 1 steps]
2.[Flow 2 steps]
 
### System Flows
1.[Flow 1 steps]
2.[Flow 2 steps]
 
## Architecture
 
### System Context
[Diagram or description of actors and system boundaries]
 
### Components
| Component | Purpose (Functionality) | Dependencies |
|-----------|------------------------|--------------|
| [Name] | [What flow it supports] | [What it needs] |
 
### API Endpoints
| Endpoint | Flow | Request | Response |
|----------|------|---------|----------|
| POST /api/x | User uploads | {...} | {...} |
 
## Key Decisions
 
### Decision 1: [Title]
-Context: [Functionality driver]
-Options: [List]
-Trade-offs: [Table]
-Decision: [Choice]
-Rationale: [Why]
 
## Implementation Roadmap
 
### Critical (Must have for core flow)
1.[Component/feature]
 
### Important (Completes flows)
1.[Component/feature]
 
### Enhancement (Improves experience)
1.[Component/feature]

Final Check

Before completing architecture design:

• [ ] All user flows mapped
• [ ] All system flows mapped
• [ ] Each component traces to functionality
• [ ] Each API endpoint traces to flow
• [ ] Decisions documented with trade-offs
• [ ] Implementation roadmap prioritized