ADR-0002 Use C4

Publication Date2021-05-11
Last Update2021-05-11


The eTryOn project will consist of a number of user-facing applications, server-side components for data storage, processing, and retrieval, and interactions with third-party APIs and supporting systems for authentication and authorization. It will be important to document these systems and their interactions to align everyone’s understanding of what we plan to build and explain how the system as a whole will work.

The software architect Simon Brown created a structured model for visualizing software architecture, the C4 model, which decomposes a system into containers and components and shows their relationships with each other and with their users. It allows the system to be viewed in a hierarchy:

  • Context diagrams (level 1): they show the system in scope and its relationship with users and other systems;
  • Container diagrams (level 2): they decompose a system into interrelated containers. A container represents an application or a data store;
  • Component diagrams (level 3): they decompose containers into interrelated components, and relate the components to other containers or other systems;
  • Code diagrams (level 4): they provide additional details about the design of the architectural elements that can be mapped to code. C4 model relies at this level on existing notations such as Unified Modelling Language (UML) or Entity Relation Diagrams (ERD).

(Reference: C4 Model).

He also provides the Structurizr tooling that allows you to express the architeture in a text-based DSL that can then be rendered at any of these levels in a number of different formats.


We will use the C4 Model to describe our system architecture.

We will use the Sturcturizr DSL to express our architecture diagrams.

We will use the Structurizr CLI and PlantUML to generate diagrams from the DSL.


Using a text-based DSL for the diagrams allows them to be kept under version control and facilitates collaboration.

The simple DSL also allows for rapid iteration as our understanding of the requirements evolves, making it easier to keep the architecture diagrams up to date.

Command-line tooling allows us to generate images from the DSL in a script or CI/CD pipeline. These images are then easily included in Markdown pages and other documents.