Help us improve
Share bugs, ideas, or general feedback.
From acc
Generates ARCHITECTURE.md files for PHP projects using DDD layers (Domain, Application, Infrastructure, Presentation). Includes directory structure, component descriptions, diagrams, and tech stack.
npx claudepluginhub dykyi-roman/awesome-claude-code --plugin accHow this skill is triggered — by the user, by Claude, or both
Slash command
/acc:architecture-doc-templateThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Generate comprehensive architecture documentation for PHP projects.
Generates architecture documents using markdown templates with C4 diagram integration (context, container, component). Creates viewpoint docs, technical overviews, and executive summaries for stakeholders.
Generates architecture documentation using arc42 or C4 models with Mermaid diagrams for system context, containers, components, plus narrative on structure, dependencies, and flows.
Generates system architecture docs with overview, components list, Mermaid diagrams for components and data flows, external dependencies, ADRs links, and dev setup instructions.
Share bugs, ideas, or general feedback.
Generate comprehensive architecture documentation for PHP projects.
# 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}
## 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
| 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
```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
| Actor | Description |
|---|---|
| {Actor 1} | {Description} |
| {Actor 2} | {Description} |
| 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
```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 | 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 |
## 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 |
# 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
[... layer descriptions ...]
| 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 |
| 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