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

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

External Systems

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

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

Architecture Decisions

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