Diagrams

This directory holds architecture diagrams for the project. The preferred diagramming standard is the C4 model.

Diagram Types

The C4 model defines four levels of detail. We use the first three; Code-level diagrams are only created when they help capture genuinely complex functionality.

• C4 Level 1 -- System Context Diagram: Shows the relationship between the user, the application, and any external systems.
• C4 Level 2 -- Container Diagram: A high-level view of the application broken down into its containers (for example, a web server, a database, a background worker).
• C4 Level 3 -- Component Diagram: A detailed view of a single container, showing its internal components and how they interact.
• Production Deployment Diagram: Captures how containers and services are deployed across the production infrastructure.

Tooling

C4 with Structurizr

Structurizr is the recommended tool for creating C4 diagrams. Define your architecture in code using the Structurizr DSL, generate the diagrams, and commit the exported output to this directory.

Mermaid

Mermaid is a lightweight, code-based diagramming tool that works directly inside Markdown. It supports sequence diagrams, flowcharts, class diagrams, state diagrams, and more. Use Mermaid when you need a quick diagram embedded in a document and do not need the full power of Structurizr.

PlantUML

PlantUML creates diagrams from plain-text descriptions. It supports a wide range of diagram types including sequence, class, activity, and deployment diagrams. PlantUML is a good choice when Mermaid lacks the specific diagram type you need.