SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsddd-architecture-doc

ddd-architecture-doc

Writing & research

View repository

Updated 10-15 21:48

About this skill

DDD Architecture Documentation

Generate comprehensive DDD architecture documentation: C4 model diagrams (L1-L4), ADRs, domain model docs, API docs, decision logs, and team communication templates.

Workflow

Follow this 5-step workflow when generating architecture documentation:

Step 1: Understand Context — Project size, team, tech stack, domain
Step 2: Identify Audiences — Business / dev / ops
Step 3: Select C4 Level — L1 for business, L2 for ops, L3 for dev team
Step 4: Check Decisions — Any existing ADRs? Need to create new ones?
Step 5: Generate Output — Combine diagrams + ADRs + templates into one doc

When info is insufficient: give a best-guess version first based on common patterns (e.g., e-commerce) + list what specific information is still needed. Never just say "Please provide more information".

Boundary

✅ Good at handling

  1. C4 model diagram generation — L1 System Context / L2 Container / L3 Component / L4 Code（Mermaid）
  2. ADR architecture decision records — template + index + status tracking
  3. Domain model documentation — aggregate descriptions + entity/value object/event lists
  4. API documentation — API specification for CQRS command/query separation

⚠️ Requires conditions

  1. Existing architecture decisions — decisions must exist before ADRs can be recorded
  2. Identified bounded contexts — at minimum, you need to know which BCs the system has before drawing a C4 L1 diagram
  3. Known tech stack — you need to know the framework/database/middleware before generating an L2 container diagram

❌ Out of scope (unsuitable scenarios)

  1. No architecture decisions → make decisions first, then document(route to ddd-architecture-selector）
  2. Solo project → README + inline comments are sufficient
  3. Architecture selection needed → ddd-architecture-selector
  4. Code review needed → ddd-code-reviewer

Audience

This skill is designed for: Backend developers (implementing DDD architectures), Software architects (evaluating and selecting patterns), Tech leads (reviewing team implementations), and DDD beginners (learning domain-driven design fundamentals).

Rules

  1. Every architecture decision must be documented as an ADR.
  2. C4 diagrams must follow Level 1→4 hierarchy.
  3. Domain model documentation must reference bounded contexts.
  4. All decision logs must include date, context, options, and rationale.

Four levels of the C4 model

DDD → C4 Mapping

C4 Level     | DDD Context                   | Audience
─────────────┼───────────────────────────────┼────────────────
L1 Context   | All bounded contexts + externals | Business, Architects
L2 Container | Per-BC deployment units        | Architects, DevOps
L3 Component | BC internal layers (Adapter/App/Domain/Infra) | Dev Team
L4 Code      | Aggregate internals (entities, VOs, events) | Developers

L1: System Context — shows the system and its external relationships

graph TB
    Customer["👤 Customer"] --> BC1["Bounded Context 1"]
    Customer --> BC2["Bounded Context 2"]
    Admin["👤 Admin"] --> BC3["Bounded Context 3"]
    BC1 --> PaymentGW["💳 Payment Gateway"]

L2: Container — deployment units of a single BC

graph TB
    Web["Web App"] --> API["API (Spring Boot)"]
    API --> DB[("Database (PostgreSQL)")]
    API --> Queue["Event Queue (RabbitMQ)"]

For complete Mermaid code examples for L3/L4, see references/01-c4-examples.md。

When to use each level: L1 for project kickoff, L2 for ops handover, L3 for daily dev reference, L4 for complex aggregates only.

ADR (Architecture Decision Record)

ADR Template

# ADR-{NNN}: {Short Title}

## Status
{Proposed / Accepted / Deprecated / Superseded}

## Context / Decision / Alternatives / Consequences
- **Context**: Why is this decision needed?
- **Decision**: What did we decide?
- **Alternatives**: Options considered with pros/cons, mark chosen
- **Consequences**: Positive + negative impacts
- **Related**: ADR-{NNN}: {related}

ADR Status Tracking Table

| ADR# | Title | Status | Date | Superseded By |
|------|-------|:------:|:----:|:----:|
| 001 | Choose COLA Architecture | Accepted | 2024-03-15 | — |
| 002 | CQRS Strategy L2 | Accepted | 2024-03-20 | — |
| 003 | MySQL over PostgreSQL | Deprecated | 2024-02-01 | ADR-005 |

Domain Model Documentation

Document each aggregate:

## Aggregate: {Name}
- **Root**: {ClassName} | **Id**: {IdType}
- **Entities**: Table of entity / owner / lifecycle
- **Value Objects**: Table of VO / fields / immutable
- **Domain Events**: Table of event / trigger / consumer
- **Invariants**: 1. {Invariant 1}
- **State Machine**: ```mermaid stateDiagram-v2```

API Documentation — CQRS command/query separation

API Type Method Example CQRS Model
Command POST/PUT/DELETE POST /orders Command Model
Query GET GET /orders?status=PAID Query Model

Command API: triggers domain behavior, publishes domain events, idempotent key required. Query API: reads from query model (may be separate read DB), no side effects.

Architecture Decision Log

Maintain a central index:

docs/adrs/
├── README.md          ← Auto-generated ADL index
├── ADR-001-title.md
└── ...

Best practices: one ADR file = one decision; ADR in the same repo as code; CI auto-generates the index.

Documentation maintenance strategy

Strategy Frequency Owner
Update ADRs + diagrams in sync during PRs Every code change Developer
Quarterly C4 diagram audit Quarterly Architect
Automatic ADL index generation Every ADR change CI
Full architecture documentation review Monthly Architecture team

Golden rule: if code changes the architecture, the doc changes in the same PR.

Gotchas — Common Pitfalls

  1. Misuse of C4 levels — each level has a clear definition; do not mix them.
  2. ADRs written too late — record decisions as they are made, even if it is just one sentence.
  3. Documentation out of sync with code — must be updated after every architecture change.
  4. Only drawing diagrams without writing decision rationale — C4 shows What, ADRs explain Why.
  5. Diagrams too complex — limit each diagram to 5-7 nodes.
  6. Over-documentation — focus on "what others need to know in order to develop".
  7. ADRs do not list alternatives — you must record why other options were not chosen.
  8. Ignoring the audience — use different C4 levels for different audiences.

FAQ

Q1: What tool should be used for documentation? Start with Mermaid, then consider Structurizr as complexity increases.

Q2: Which C4 levels need to be drawn? L1 + L2 are mandatory; L3 depends on team size (recommended for >5 people).

Q3: How do you ensure documentation does not expire? PR checkboxes + CI checks for ADR consistency + monthly review.

Q4: What if a legacy system has no documentation? First draw an AS-IS L1 diagram → record key ADRs → improve one BC per sprint.

Q5: How detailed should an ADR be? Must include at least background, decision, alternatives (≥2), and impact.

Q6: How should multiple people editing one BC's document at the same time be handled? The Git conflict resolution mechanism is sufficient; review the document in sync during PR Review.

Security & Safety

This skill is pure documentation. It does not collect user data, does not access external services or networks, and contains no executable scripts.

Keywords

  • Keywords: architecture documentation, 架构文档, ADR, C4 diagram, C4 模型, architecture decision record, 架构决策记录, domain model doc, 领域模型文档, 技术文档, 架构图, system context, container diagram, component diagram, code diagram, 架构评审, 文档模板, architecture decision log

References

File Content When to Reference
references/01-c4-examples.md Full C4 L1-L4 Mermaid examples for e-commerce User needs complete C4 diagrams to copy-paste
references/02-adr-templates.md 3 ADR template variants (standard, lightweight, tech) User needs to write a new ADR
references/03-doc-templates.md 3 architecture doc templates (full, lightweight, onboarding) User needs a document structure to start with
references/04-toolchain.md Tool recommendations (Structurizr, Mermaid, PlantUML, ArchUnit) User asks about tools or automation
references/05-team-templates.md Team communication templates (review request, change notice) User needs to notify or review with team
references/06-arch-decision-log.md ADL index format + CI automation User needs to maintain or automate ADR tracking
references/07-domain-model-doc.md Aggregate/BC documentation patterns User needs to document domain models
references/08-api-doc-patterns.md CQRS API documentation patterns + OpenAPI spec User needs to document APIs with CQRS
references/09-trace-anti-patterns.md Architecture doc anti-patterns (5 categories) User needs to avoid common documentation mistakes
references/10-faq-deep.md In-depth FAQ (microservices ADR, legacy systems, security) User has advanced or edge-case questions

Related Skills

  • ddd-architecture-selector — Architecture selection (before you document, make decisions). Install: npx skills add full-stack-skills/ddd-skills --skill ddd-architecture-selector.
  • ddd-architecture-evaluator — Periodic architecture health check. Install: npx skills add full-stack-skills/ddd-skills --skill ddd-architecture-evaluator.
  • ddd-code-reviewer — Code-level DDD compliance check. Install: npx skills add full-stack-skills/ddd-skills --skill ddd-code-reviewer.
  • ddd-cqrs-architecture — CQRS detail for API documentation. Install: npx skills add full-stack-skills/ddd-skills --skill ddd-cqrs-architecture.
  • ddd-architecture-awesome — DDD concept overview. Install: npx skills add full-stack-skills/ddd-skills --skill ddd-architecture-awesome.