architecture-doc-template

Architecture Documentation Template Generator

Generate comprehensive architecture documentation for PHP projects.

Document Structure

# Architecture

## Overview
{high-level description}

## Directory Structure
{annotated project tree}

## System Context
{C4 context diagram}

## Architecture Layers
{layer descriptions}

## Components
{component descriptions}

## Data Flow
{sequence diagrams}

## Technology Stack
{technology decisions}

## Architecture Decisions
{link to ADRs}

## Deployment
{deployment diagram}

Section Templates

Directory Structure Section

## Directory Structure

project/ ├── src/ # Source code │ ├── Domain/ # Domain Layer (DDD) │ │ ├── Entity/ # Domain entities │ │ ├── ValueObject/ # Value objects │ │ ├── Repository/ # Repository interfaces │ │ ├── Service/ # Domain services │ │ └── Event/ # Domain events │ ├── Application/ # Application Layer │ │ ├── UseCase/ # Use cases / Commands / Queries │ │ ├── DTO/ # Data Transfer Objects │ │ └── Service/ # Application services │ ├── Infrastructure/ # Infrastructure Layer │ │ ├── Persistence/ # Repository implementations │ │ ├── Http/ # HTTP clients │ │ ├── Messaging/ # Queue adapters │ │ └── Cache/ # Cache adapters │ └── Presentation/ # Presentation Layer │ ├── Api/ # REST API (Actions, Requests, Responses) │ ├── Web/ # Web controllers │ └── Console/ # CLI commands ├── tests/ # Test suite │ ├── Unit/ # Unit tests (mirrors src/) │ ├── Integration/ # Integration tests │ └── Functional/ # E2E / Functional tests ├── config/ # Configuration files ├── public/ # Web root ├── docker/ # Docker configuration └── docs/ # Documentation ├── architecture/ # Architecture docs ├── adr/ # Architecture Decision Records └── api/ # API documentation

### Generation Command

```bash
tree -L 3 -I 'vendor|node_modules|.git|var|cache' --dirsfirst

Annotation Rules

Rule	Description
Layer name	Add DDD layer in comment
Purpose	Describe directory purpose
Depth	Max 3 levels in main docs
Details	Link to subdirectory READMEs

### Overview Section

```markdown
## Overview

{Project Name} follows {Architecture Style} (e.g., Clean Architecture, DDD, Hexagonal).

### Key Principles

- **Separation of Concerns** — Each layer has distinct responsibility
- **Dependency Rule** — Dependencies point inward (Domain is center)
- **Testability** — Business logic isolated from infrastructure
- **Framework Independence** — Core logic doesn't depend on frameworks

### High-Level Structure

┌─────────────────────────────────────────┐ │ Presentation Layer │ │ (Actions, Responders) │ ├─────────────────────────────────────────┤ │ Application Layer │ │ (UseCases, Services) │ ├─────────────────────────────────────────┤ │ Domain Layer │ │ (Entities, Value Objects, Events) │ ├─────────────────────────────────────────┤ │ Infrastructure Layer │ │ (Repositories, Adapters, DB) │ └─────────────────────────────────────────┘

System Context Section

## System Context

```mermaid
flowchart TB
    subgraph boundary["{System Name}"]
        S[("{System}\n{Brief Description}")]
    end

    U1[("👤 {Actor 1}")]
    U2[("👤 {Actor 2}")]
    ES1[("📦 {External System 1}")]
    ES2[("📦 {External System 2}")]

    U1 -->|"{interaction}"| S
    U2 -->|"{interaction}"| S
    S -->|"{integration}"| ES1
    S -->|"{integration}"| ES2

Actors

Actor	Description
{Actor 1}	{Description}
{Actor 2}	{Description}

External Systems

System	Purpose	Integration
{System 1}	{Purpose}	{Protocol/API}
{System 2}	{Purpose}	{Protocol/API}

### Architecture Layers Section

```markdown
## Architecture Layers

### Presentation Layer

**Responsibility:** Handle HTTP requests and responses

**Components:**
- `Api/` — REST API endpoints (Actions + Responders)
- `Web/` — Web interface (Actions + Responders)
- `Console/` — CLI commands

**Rules:**
- No business logic
- Validate input
- Call Application layer
- Format output

### Application Layer

**Responsibility:** Orchestrate business operations

**Components:**
- `UseCase/` — Application-specific business rules
- `Service/` — Cross-cutting application services
- `DTO/` — Data transfer objects

**Rules:**
- Orchestrate Domain objects
- Handle transactions
- No infrastructure concerns

### Domain Layer

**Responsibility:** Core business logic

**Components:**
- `Entity/` — Business objects with identity
- `ValueObject/` — Immutable value concepts
- `Event/` — Domain events
- `Repository/` — Repository interfaces
- `Service/` — Domain services

**Rules:**
- No external dependencies
- Pure business logic
- Self-validating objects

### Infrastructure Layer

**Responsibility:** Technical implementations

**Components:**
- `Persistence/` — Repository implementations
- `Adapter/` — External service adapters
- `Cache/` — Caching implementations
- `Queue/` — Queue implementations

**Rules:**
- Implement Domain interfaces
- Handle technical concerns
- No business logic

Components Section

## Components

```mermaid
flowchart TB
    subgraph presentation[Presentation Layer]
        AC[Action]
        RS[Responder]
    end

    subgraph application[Application Layer]
        UC[UseCase]
        AS[AppService]
    end

    subgraph domain[Domain Layer]
        EN[Entity]
        VO[ValueObject]
        DE[DomainEvent]
        RI[Repository<br/>Interface]
    end

    subgraph infrastructure[Infrastructure Layer]
        RP[Repository<br/>Impl]
        AD[Adapter]
        CA[Cache]
    end

    AC --> UC
    UC --> EN
    UC --> RI
    RP -.-> RI
    RP --> CA

Component Descriptions

Component	Layer	Responsibility
Action	Presentation	HTTP request handling
Responder	Presentation	HTTP response building
UseCase	Application	Business operation orchestration
Entity	Domain	Business object with identity
ValueObject	Domain	Immutable value concept
Repository	Infrastructure	Data persistence

### Data Flow Section

```markdown
## Data Flow

### {Operation Name} Flow

```mermaid
sequenceDiagram
    participant C as Client
    participant A as Action
    participant U as UseCase
    participant E as Entity
    participant R as Repository
    participant D as Database

    C->>A: {Request}
    A->>A: Validate & Map to DTO
    A->>U: Execute(dto)
    U->>R: find(id)
    R->>D: SELECT
    D-->>R: row
    R-->>U: entity
    U->>E: {operation}()
    E-->>U: result
    U->>R: save(entity)
    R->>D: UPDATE
    D-->>R: ok
    U-->>A: Result
    A->>A: Build Response
    A-->>C: {Response}

### Technology Stack Section

```markdown
## Technology Stack

| Layer | Technology | Purpose |
|-------|------------|---------|
| Language | PHP 8.4 | Type safety, modern features |
| Framework | Symfony 7.x | HTTP, DI, Console |
| ORM | Doctrine 3.x | Database abstraction |
| Database | PostgreSQL 16 | Primary storage |
| Cache | Redis 7.x | Session, cache |
| Queue | RabbitMQ 3.x | Async processing |
| API | OpenAPI 3.1 | API specification |

### Technology Decisions

| Decision | Rationale |
|----------|-----------|
| PostgreSQL over MySQL | JSONB support, better type system |
| Symfony over Laravel | More explicit, better DI |
| Redis over Memcached | Data structures, persistence |

ADR Link Section

## Architecture Decisions

Key decisions are documented as ADRs:

| ADR | Status | Title |
|-----|--------|-------|
| [ADR-001](docs/adr/001-use-ddd.md) | Accepted | Use DDD Architecture |
| [ADR-002](docs/adr/002-cqrs.md) | Accepted | Implement CQRS |
| [ADR-003](docs/adr/003-event-sourcing.md) | Proposed | Consider Event Sourcing |

Complete Example

# Architecture

## Overview

Order Management System follows Domain-Driven Design with Clean Architecture principles.

### Key Principles

- **Domain-Centric** — Business logic in Domain layer
- **Dependency Inversion** — Abstractions over implementations
- **Bounded Contexts** — Order, Inventory, Shipping

## Directory Structure

order-management/ ├── src/ │ ├── Order/ # Order Bounded Context │ │ ├── Domain/ # Domain Layer │ │ ├── Application/ # Application Layer │ │ ├── Infrastructure/ # Infrastructure Layer │ │ └── Presentation/ # Presentation Layer │ ├── Inventory/ # Inventory Bounded Context │ └── Shipping/ # Shipping Bounded Context ├── tests/ ├── config/ └── docs/

## System Context

```mermaid
flowchart TB
    subgraph boundary["Order Management System"]
        S[("📦 OMS\nManages orders lifecycle")]
    end

    Customer[("👤 Customer")]
    Admin[("👤 Admin")]
    Payment[("💳 Payment Gateway")]
    Shipping[("🚚 Shipping Provider")]

    Customer -->|"Place orders"| S
    Admin -->|"Manage orders"| S
    S -->|"Process payments"| Payment
    S -->|"Ship orders"| Shipping

Architecture Layers

[... layer descriptions ...]

Technology Stack

Layer	Technology	Purpose
Language	PHP 8.4	Type safety
Framework	Symfony 7.2	HTTP, DI
Database	PostgreSQL 16	Storage
Cache	Redis 7.4	Performance
Queue	RabbitMQ 3.13	Async

Architecture Decisions

ADR	Status	Title
ADR-001	Accepted	Use DDD
ADR-002	Accepted	Use CQRS

## Generation Instructions

When generating ARCHITECTURE.md:

1. **Analyze** project structure for layer organization
2. **Identify** architectural style (DDD, Clean, Hexagonal)
3. **Map** components to layers
4. **Create** context diagram with actors/systems
5. **Generate** component diagram
6. **List** technology stack from `composer.json`
7. **Link** existing ADRs if present