Claude-Code-Workflow/.claude/skills/spec-generator/templates/architecture-doc.md

Architecture Document Template (Directory Structure)

Template for generating architecture decision documents as a directory of individual ADR files in Phase 4.

Usage Context

Phase	Usage
Phase 4 (Architecture)	Generate architecture/ directory from requirements analysis
Output Location	{workDir}/architecture/

Output Structure

{workDir}/architecture/
├── _index.md                      # Overview, components, tech stack, data model, security
├── ADR-001-{slug}.md              # Individual Architecture Decision Record
├── ADR-002-{slug}.md
└── ...

---

Template: _index.md

---
session_id: {session_id}
phase: 4
document_type: architecture-index
status: draft
generated_at: {timestamp}
version: 1
dependencies:
  - ../spec-config.json
  - ../product-brief.md
  - ../requirements/_index.md
---

# Architecture: {product_name}

{executive_summary - high-level architecture approach and key decisions}

## System Overview

### Architecture Style
{description of chosen architecture style: microservices, monolith, serverless, etc.}

### System Context Diagram

```mermaid
C4Context
    title System Context Diagram
    Person(user, "User", "Primary user")
    System(system, "{product_name}", "Core system")
    System_Ext(ext1, "{external_system}", "{description}")
    Rel(user, system, "Uses")
    Rel(system, ext1, "Integrates with")

Component Architecture

Component Diagram

graph TD
    subgraph "{product_name}"
        A[Component A] --> B[Component B]
        B --> C[Component C]
        A --> D[Component D]
    end
    B --> E[External Service]

Component Descriptions

Component	Responsibility	Technology	Dependencies
{component_name}	{what it does}	{tech stack}	{depends on}

Technology Stack

Core Technologies

Layer	Technology	Version	Rationale
Frontend	{technology}	{version}	{why chosen}
Backend	{technology}	{version}	{why chosen}
Database	{technology}	{version}	{why chosen}
Infrastructure	{technology}	{version}	{why chosen}

Key Libraries & Frameworks

Library	Purpose	License
{library_name}	{purpose}	{license}

Architecture Decision Records

ADR	Title	Status	Key Choice
ADR-001	{title}	Accepted	{one-line summary}
ADR-002	{title}	Accepted	{one-line summary}
ADR-003	{title}	Proposed	{one-line summary}

Data Architecture

Data Model

erDiagram
    ENTITY_A ||--o{ ENTITY_B : "has many"
    ENTITY_A {
        string id PK
        string name
        datetime created_at
    }
    ENTITY_B {
        string id PK
        string entity_a_id FK
        string value
    }

Data Storage Strategy

Data Type	Storage	Retention	Backup
{type}	{storage solution}	{retention policy}	{backup strategy}

API Design

API Overview

Endpoint	Method	Purpose	Auth
{/api/resource}	{GET/POST/etc}	{purpose}	{auth type}

Security Architecture

Security Controls

Control	Implementation	Requirement
Authentication	{approach}	NFR-S-{NNN}
Authorization	{approach}	NFR-S-{NNN}
Data Protection	{approach}	NFR-S-{NNN}

Infrastructure & Deployment

Deployment Architecture

{description of deployment model: containers, serverless, VMs, etc.}

Environment Strategy

Environment	Purpose	Configuration
Development	Local development	{config}
Staging	Pre-production testing	{config}
Production	Live system	{config}

Codebase Integration

{if has_codebase is true:}

Existing Code Mapping

New Component	Existing Module	Integration Type	Notes
{component}	{existing module path}	Extend/Replace/New	{notes}

Migration Notes

{any migration considerations for existing code}

Quality Attributes

Attribute	Target	Measurement	ADR Reference
Performance	{target}	{how measured}	ADR-{NNN}
Scalability	{target}	{how measured}	ADR-{NNN}
Reliability	{target}	{how measured}	ADR-{NNN}

State Machine

{For each core entity with a lifecycle (e.g., Order, Session, Task):}

{Entity} Lifecycle

{ASCII state diagram showing all states, transitions, triggers, and error paths}

  ┌──────────┐
  │  Created  │
  └─────┬────┘
        │ start()
        ▼
  ┌──────────┐     error      ┌──────────┐
  │  Running  │ ──────────▶   │  Failed   │
  └─────┬────┘               └──────────┘
        │ complete()
        ▼
  ┌──────────┐
  │ Completed │
  └──────────┘

From State	Event	To State	Side Effects	Error Handling
{from}	{event}	{to}	{side_effects}	{error_behavior}

Configuration Model

Required Configuration

Field	Type	Default	Constraint	Description
{field_name}	{string/number/boolean/enum}	{default_value}	{validation rule}	{description}

Optional Configuration

Field	Type	Default	Constraint	Description
{field_name}	{type}	{default}	{constraint}	{description}

Environment Variables

Variable	Maps To	Required
{ENV_VAR}	{config_field}	{yes/no}

Error Handling

Error Classification

Category	Severity	Retry	Example
Transient	Low	Yes, with backoff	Network timeout, rate limit
Permanent	High	No	Invalid configuration, auth failure
Degraded	Medium	Partial	Dependency unavailable, fallback active

Per-Component Error Strategy

Component	Error Scenario	Behavior	Recovery
{component}	{scenario}	{MUST/SHOULD behavior}	{recovery strategy}

Observability

Metrics

Metric Name	Type	Labels	Description
{metric_name}	{counter/gauge/histogram}	{label1, label2}	{what it measures}

Logging

Event	Level	Fields	Description
{event_name}	{INFO/WARN/ERROR}	{structured fields}	{when logged}

Health Checks

Check	Endpoint	Interval	Failure Action
{check_name}	{/health/xxx}	{duration}	{action on failure}

Trust & Safety

Trust Levels

Level	Description	Approval Required	Allowed Operations
High Trust	{description}	None	{operations}
Standard	{description}	{approval type}	{operations}
Low Trust	{description}	{approval type}	{operations}

Security Controls

{Detailed security controls beyond the basic auth covered in Security Architecture}

Implementation Guidance

Key Decisions for Implementers

Decision	Options	Recommendation	Rationale
{decision_area}	{option_1, option_2}	{recommended}	{why}

Implementation Order

1. {component/module 1}: {why first}
2. {component/module 2}: {depends on #1}

Testing Strategy

Layer	Scope	Tools	Coverage Target
Unit	{scope}	{tools}	{target}
Integration	{scope}	{tools}	{target}
E2E	{scope}	{tools}	{target}

Risks & Mitigations

Risk	Impact	Probability	Mitigation
{risk}	High/Medium/Low	High/Medium/Low	{mitigation approach}

Open Questions

• {architectural question 1}
• {architectural question 2}

References

• Derived from: Requirements, Product Brief
• Next: Epics & Stories

---

## Template: ADR-NNN-{slug}.md (Individual Architecture Decision Record)

```markdown
---
id: ADR-{NNN}
status: Accepted
traces_to: [{REQ-NNN}, {NFR-X-NNN}]
date: {timestamp}
---

# ADR-{NNN}: {decision_title}

## Context

{what is the situation that motivates this decision}

## Decision

{what is the chosen approach}

## Alternatives Considered

| Option | Pros | Cons |
|--------|------|------|
| {option_1 - chosen} | {pros} | {cons} |
| {option_2} | {pros} | {cons} |
| {option_3} | {pros} | {cons} |

## Consequences

- **Positive**: {positive outcomes}
- **Negative**: {tradeoffs accepted}
- **Risks**: {risks to monitor}

## Traces

- **Requirements**: [REQ-{NNN}](../requirements/REQ-{NNN}-{slug}.md), [NFR-X-{NNN}](../requirements/NFR-X-{NNN}-{slug}.md)
- **Implemented by**: [EPIC-{NNN}](../epics/EPIC-{NNN}-{slug}.md) (added in Phase 5)

---

Variable Descriptions

Variable	Source	Description
{session_id}	spec-config.json	Session identifier
{timestamp}	Runtime	ISO8601 generation timestamp
{product_name}	product-brief.md	Product/feature name
{NNN}	Auto-increment	ADR/requirement number
{slug}	Auto-generated	Kebab-case from decision title
{has_codebase}	spec-config.json	Whether existing codebase exists