2. arc42 as Architecture Documentation Template

Status

Accepted

Date

2026-03-25

Context

The project requires architecture documentation that is understandable for both new and existing contributors and traceable in retrospect. The documentation must be maintainable iteratively without requiring a full restructuring on every change.

Decision

We use arc42 as the template for architecture documentation. Within the arc42 structure, we additionally use C4 diagrams rendered from PlantUML source files.

Rationale

  • arc42 is an established standard, familiar to many developers

  • The template provides a clear chapter structure that can be filled iteratively

  • C4 diagrams integrate well into arc42 and provide consistent levels of abstraction

  • arc42 is tool-independent and works with AsciiDoc and GitHub Pages without additional dependencies

  • The structure supports multiple audiences and their perspectives:

    • High-level overview for stakeholders

    • Technical detail for developers

Considered Alternatives

C4 Model Only

Exclusively C4 diagrams as documentation.

  • Pros

    • Visually accessible and quick to grasp

    • Clear abstraction levels (Context → Container → Component → Code)

  • Cons

    • No place for quality requirements, risks, or decisions

    • Textual explanations are missing

    • Not sufficient as complete architecture documentation on its own

Free Structure

No prescribed template; documentation at discretion.

  • Pros

    • Maximum flexibility

  • Cons

    • No consistent structure; hard to navigate for new contributors

    • Risk of gaps because no checklist exists

No Documentation

Deliberate omission of architecture documentation.

  • Pros

    • No initial effort

  • Cons

    • Knowledge remains implicit and is lost when contributors leave

    • New contributors face a much higher barrier to entry

    • Architecture decisions are not traceable

Consequences

  • Architecture documentation lives under docs/Architecture/

  • Architecture decisions are maintained separately as ADRs and referenced from arc42 chapter 9

  • C4 diagrams written as PlantUML source files are embedded as supplementary visuals

  • New contributors encounter a familiar structure and can navigate directly to relevant chapters