Skip to content

EventCatalog as Living Architecture Documentation

Context and Problem Statement

The project follows DDD hexagonal architecture with 4 bounded contexts, 2 services, and 8 port Protocols. Static documentation in mkdocs captures design decisions (ADRs) and technical details well, but lacks interactive visualization of domain relationships, service dependencies, and request flows.

How should we provide a navigable, visual overview of the architecture that stays synchronized with the codebase?

Decision Drivers

  • DDD benefits from visual context maps showing bounded context relationships
  • Port-adapter mappings and service flows are hard to grasp from prose alone
  • The architecture will grow (Cognito adapter, HTTP adapter) — documentation must scale
  • The team already uses mkdocs-material for technical documentation
  • EventCatalog provides interactive visualizations of domains, services, and flows

Considered Options

  • Mermaid diagrams in mkdocs (static, code-as-diagrams)
  • EventCatalog standalone (replace mkdocs entirely)
  • EventCatalog alongside mkdocs (two complementary sites)

Decision Outcome

Chosen option: "EventCatalog alongside mkdocs", because each tool excels at different aspects of documentation.

Responsibilities

Aspect Tool Rationale
ADRs, technical guides, API docs mkdocs-material Markdown-native, Python ecosystem, search
Domain map, service graph, flows EventCatalog Interactive visualizer, DDD-native primitives
Cross-reference Both Bidirectional links between sites

DDD Mapping

DDD Concept EventCatalog Primitive
Bounded Context Domain
Application Service Service
Input Port (use case) Command
Output Port (query-side) Query
Domain Event (future) Event
Use case sequence Flow

Location

EventCatalog lives at docs/architecture/eventcatalog/ — colocated with architecture documentation, excluded from mkdocs build via exclude_docs.

Consequences

  • Good, because architects and developers get an interactive visual overview
  • Good, because DDD concepts (domains, services, events) are first-class catalog entries
  • Good, because flows visualize request paths through the hexagonal architecture
  • Neutral, because it introduces a Node.js toolchain alongside the Python project
  • Bad, because two documentation sites require separate builds and deployment

Confirmation

  • cd docs/architecture/eventcatalog && npm run dev serves the catalog on port 3100
  • Visualiser shows 4 domains with 2 services and their relationships
  • All 4 flows are navigable with step-by-step visualization
  • Cross-links between EventCatalog and mkdocs resolve correctly

More Information