Skip to content

TEMPLATE.md

Latest commit

 

History

History
523 lines (386 loc) · 11.9 KB

TEMPLATE.md

File metadata and controls

523 lines (386 loc) · 11.9 KB

{{PROJECT_NAME}} — Architecture Documentation

Overview

{{Brief description of the system, its purpose, and high-level architecture style}}

Document Navigation

Sections Content Audience
1-4 Business context, requirements, constraints Product, new team members
5-7 Technical implementation, deployment Developers, DevOps
8 Crosscutting concerns All technical roles
9-11 Decisions, quality, risks Architects, tech leads
12 Glossary Everyone

1. Introduction and Goals

1.1 Requirements

Business Requirements:

  • {{Why does this system exist? What business problem does it solve?}}
  • {{Who benefits from this system?}}

Functional Requirements:

  • {{Core capability 1}}
  • {{Core capability 2}}
  • {{Core capability 3}}

Non-functional Requirements:

  • {{Performance: response times, throughput}}
  • {{Availability: uptime targets}}
  • {{Scalability: expected load growth}}

1.2 Quality Goals

Priority Goal Metric
1 {{Primary quality}} {{How you measure it}}
2 {{Secondary quality}} {{How you measure it}}
3 {{Tertiary quality}} {{How you measure it}}

1.3 Stakeholders

Role Expectations
{{Role 1}} {{What they need from the system}}
{{Role 2}} {{What they need from the system}}

2. Constraints

2.1 Technical Constraints

  • Language/Runtime: {{e.g., Go 1.23+, Node 20+}}
  • Database: {{e.g., PostgreSQL 15+, must use existing cluster}}
  • Protocol: {{e.g., gRPC, REST, GraphQL}}
  • Infrastructure: {{e.g., AWS only, on-premise, Kubernetes}}

2.2 Organizational Constraints

  • Team: {{Size, key skills, availability}}
  • Process: {{CI/CD requirements, approval flows}}
  • Timeline: {{Hard deadlines, phased delivery}}

2.3 External Constraints

  • Compliance: {{GDPR, HIPAA, SOC2, etc.}}
  • Licensing: {{Open source requirements, vendor lock-in concerns}}
  • SLAs: {{External service dependencies, uptime commitments}}

3. Context and Scope

3.1 System Context (C1)

graph TB
    user[👤 User]
    admin[👤 Admin]

    system[System Name<br/>Brief description]

    external1[[External System 1]]
    external2[[External System 2]]

    user --> system
    admin --> system
    system --> external1
    system --> external2
Loading

3.2 Technical Context

External System Protocol Purpose
{{System 1}} {{REST/gRPC/etc}} {{What data/functionality}}
{{System 2}} {{Protocol}} {{Purpose}}

4. Solution Strategy

4.1 Architectural Approach

Pattern Rationale
{{Pattern 1, e.g., Modular Monolith}} {{Why this over alternatives}}
{{Pattern 2, e.g., Event Sourcing}} {{Why this over alternatives}}

4.2 Technology Choices

Aspect Choice Rationale
{{Language}} {{Go/Rust/etc}} {{Why}}
{{Database}} {{Postgres/MongoDB/etc}} {{Why}}
{{Communication}} {{gRPC/REST/etc}} {{Why}}

5. Building Block View

5.1 Container Diagram (C2)

graph TB
    subgraph system[System Name]
        api[🌐 API Gateway<br/>:8080]
        service[⚙️ Core Service<br/>:50051]
        db[(Database<br/>:5432)]

        api --> service
        service --> db
    end

    user[👤 User] --> api
    external[[External API]] --> service
Loading

5.2 Component Diagram (C3)

graph TB
    subgraph service[Core Service]
        handler[Handler Layer]
        business[Business Logic]
        repo[Repository]
        adapter[External Adapters]
    end

    handler --> business
    business --> repo
    business --> adapter
    repo --> db[(Database)]
    adapter --> external[[External API]]
Loading

5.3 Component Responsibilities

Component Responsibility Dependencies
{{Component 1}} {{Single responsibility}} {{What it needs}}
{{Component 2}} {{Single responsibility}} {{What it needs}}

6. Runtime View

6.1 Key Scenarios

Scenario: {{Name, e.g., User Authentication}}

sequenceDiagram
    participant User
    participant API
    participant Service
    participant DB

    User->>API: 1. Request
    API->>Service: 2. Forward
    Service->>DB: 3. Query
    DB-->>Service: 4. Result
    Service-->>API: 5. Response
    API-->>User: 6. Result
Loading

6.2 Error Handling

  • External API unavailable: {{Graceful degradation strategy}}
  • Database timeout: {{Retry policy, circuit breaker}}
  • Invalid input: {{Validation approach}}

7. Deployment View

7.1 Infrastructure

graph TB
    subgraph prod[Production]
        lb[Load Balancer]
        app1[App Instance 1]
        app2[App Instance 2]
        db[(Primary DB)]
        replica[(Read Replica)]
    end

    lb --> app1
    lb --> app2
    app1 --> db
    app2 --> db
    db --> replica
Loading

7.2 Environment Configuration

Environment Purpose Key Differences
Development Local dev In-memory DB, mocked externals
Staging Pre-prod testing Production-like, synthetic data
Production Live system Full redundancy, real data

8. Crosscutting Concepts

8.1 Security

  • Authentication: {{JWT, API keys, OAuth, etc.}}
  • Authorization: {{RBAC, ABAC, per-resource}}
  • Encryption: {{At rest, in transit, key management}}

8.2 Observability

  • Logging: {{Format, levels, aggregation}}
  • Metrics: {{What's measured, alerting thresholds}}
  • Tracing: {{Correlation IDs, distributed tracing}}

8.3 Error Handling

  • Error codes: {{Structured error responses}}
  • Retry policy: {{Exponential backoff, max attempts}}
  • Circuit breaker: {{When and how}}

9. Architecture Decisions

ADR-001: {{Decision Title}}

  • Status: accepted
  • Context: {{What problem or question triggered this decision}}
  • Decision: {{What was decided}}
  • Consequences:
    • ➕ {{Positive outcome}}
    • ➕ {{Another benefit}}
    • ➖ {{Tradeoff or downside}}

ADR-002: {{Decision Title}}

  • Status: accepted
  • Context: {{Context}}
  • Decision: {{Decision}}
  • Consequences:
    • ➕ {{Positive}}
    • ➖ {{Negative}}

10. Quality Requirements

10.1 Quality Tree

graph TB
    root[System Quality]

    root --> perf[Performance]
    perf --> p1[API < 200ms p95]
    perf --> p2[Throughput > 1000 RPS]

    root --> avail[Availability]
    avail --> a1[99.9% uptime]
    avail --> a2[Graceful degradation]

    root --> sec[Security]
    sec --> s1[Encrypted at rest]
    sec --> s2[Audit logging]
Loading

10.2 Quality Scenarios

Quality Scenario Metric Status
Performance Peak load of 100 concurrent users p95 < 500ms Planned
Availability Database failover Recovery < 30s Implemented
Security Unauthorized access attempt 100% blocked Implemented

11. Risks and Technical Debt

11.1 Risks

Risk Probability Impact Mitigation
{{Risk 1}} High/Medium/Low High/Medium/Low {{Plan}}
{{Risk 2}} {{Prob}} {{Impact}} {{Plan}}

11.2 Technical Debt

Debt 1: {{Title}}

  • Description: {{What was compromised}}
  • Impact: {{Current pain}}
  • Resolution: {{Plan and timeline}}

12. Glossary

Term Definition
{{Term 1}} {{Definition}}
{{Term 2}} {{Definition}}

Document Metadata

  • Version: {{1.0}}
  • Last Updated: {{YYYY-MM-DD}}
  • Owner: {{Name/Team}}
  • Status: Draft | Active | Deprecated