admin/.cursor/skills/plan/templates/architecture.md

Architecture Document Template

Use this template for the architecture document. Save as _docs/02_document/architecture.md.

---

# [System Name] — Architecture

## 1. System Context

**Problem being solved**: [One paragraph summarizing the problem from problem.md]

**System boundaries**: [What is inside the system vs. external]

**External systems**:

| System | Integration Type | Direction | Purpose |
|--------|-----------------|-----------|---------|
| [name] | REST / Queue / DB / File | Inbound / Outbound / Both | [why] |

## 2. Technology Stack

| Layer | Technology | Version | Rationale |
|-------|-----------|---------|-----------|
| Language | | | |
| Framework | | | |
| Database | | | |
| Cache | | | |
| Message Queue | | | |
| Hosting | | | |
| CI/CD | | | |

**Key constraints from restrictions.md**:
- [Constraint 1 and how it affects technology choices]
- [Constraint 2]

## 3. Deployment Model

**Environments**: Development, Staging, Production

**Infrastructure**:
- [Cloud provider / On-prem / Hybrid]
- [Container orchestration if applicable]
- [Scaling strategy: horizontal / vertical / auto]

**Environment-specific configuration**:

| Config | Development | Production |
|--------|-------------|------------|
| Database | [local/docker] | [managed service] |
| Secrets | [.env file] | [secret manager] |
| Logging | [console] | [centralized] |

## 4. Data Model Overview

> High-level data model covering the entire system. Detailed per-component models go in component specs.

**Core entities**:

| Entity | Description | Owned By Component |
|--------|-------------|--------------------|
| [entity] | [what it represents] | [component ##] |

**Key relationships**:
- [Entity A] → [Entity B]: [relationship description]

**Data flow summary**:
- [Source] → [Transform] → [Destination]: [what data and why]

## 5. Integration Points

### Internal Communication

| From | To | Protocol | Pattern | Notes |
|------|----|----------|---------|-------|
| [component] | [component] | Sync REST / Async Queue / Direct call | Request-Response / Event / Command | |

### External Integrations

| External System | Protocol | Auth | Rate Limits | Failure Mode |
|----------------|----------|------|-------------|--------------|
| [system] | [REST/gRPC/etc] | [API key/OAuth/etc] | [limits] | [retry/circuit breaker/fallback] |

## 6. Non-Functional Requirements

| Requirement | Target | Measurement | Priority |
|------------|--------|-------------|----------|
| Availability | [e.g., 99.9%] | [how measured] | High/Medium/Low |
| Latency (p95) | [e.g., <200ms] | [endpoint/operation] | |
| Throughput | [e.g., 1000 req/s] | [peak/sustained] | |
| Data retention | [e.g., 90 days] | [which data] | |
| Recovery (RPO/RTO) | [e.g., RPO 1hr, RTO 4hr] | | |
| Scalability | [e.g., 10x current load] | [timeline] | |

## 7. Security Architecture

**Authentication**: [mechanism — JWT / session / API key]

**Authorization**: [RBAC / ABAC / per-resource]

**Data protection**:
- At rest: [encryption method]
- In transit: [TLS version]
- Secrets management: [tool/approach]

**Audit logging**: [what is logged, where, retention]

## 8. Key Architectural Decisions

Record significant decisions that shaped the architecture.

### ADR-001: [Decision Title]

**Context**: [Why this decision was needed]

**Decision**: [What was decided]

**Alternatives considered**:
1. [Alternative 1] — rejected because [reason]
2. [Alternative 2] — rejected because [reason]

**Consequences**: [Trade-offs accepted]

### ADR-002: [Decision Title]

...