CTN Documentation Guidelines

1. Where the documentation lives

The CTN architecture documentation lives in the CNCL-BDI GitHub repository, alongside the source code that implements it:

• Repository: https://github.com/Basic-Data-Infrastructure/CNCL-BDI
• Documentation root: docs/
• Architecture chapters (this set): docs/arc42/
• Architecture Decision Records: docs/arc42/09-decisions/

Keeping the documentation in the same repository as the code has three concrete benefits:

1. Versioning comes for free. Every change is a git commit; every release tag captures both the code and the documentation that described it at that moment.
2. Pull-requests are the change process. Documentation changes go through the same review workflow as code, which means the architecture board reviews proposals before they land on main.
3. History is queryable. git log docs/arc42/05-building-blocks/ctn-association-register.md shows exactly when and why a building block changed — and git blame ties any sentence in the document back to a commit, author and date.

2. Format: Markdown

All technical documentation is written in Markdown (CommonMark + GitHub Flavored Markdown). Markdown is the right format for this repository because:

• It is plain text, so it diffs cleanly in pull requests.
• It is portable — readable in any editor, on GitHub’s web view, in static-site generators, and in IDEs.
• It supports embedded diagrams via Mermaid (see §5) without needing a separate binary format.
• It is the de-facto standard for technical documentation in open-source projects, so anyone joining the project knows how to read and edit it.

Conventions

• Use kebab-case.md for filenames (e.g. ctn-association-register.md).

• Every document starts with a YAML front-matter block:

  ---
  status: Review        # Draft | Review | Published
  lastUpdate: 2026-05-29
  ---

• The first heading after the front-matter is # Title (one H1 per document).

• Cross-references use relative paths between Markdown files so that they keep working both on GitHub and in offline checkouts.

3. Editing — Typora for people who don’t live in IDEs

For contributors who do not regularly work in a code editor, Typora is the recommended desktop editor. Typora gives you a WYSIWYG view of the Markdown — what you type renders inline as headings, lists, tables, and so on — without hiding the underlying Markdown source. That makes it usable both for newcomers (it looks like a normal document editor) and for collaborators who want to see exactly what is going into the repository (the source is one click away).

Practical notes:

• Open the folder, not a single file. Open docs/arc42/ (or the repository root) as a project in Typora’s file-tree panel; that gives you cross-document navigation and link-completion.
• Mermaid diagrams render automatically in Typora’s preview. You can write and preview them without leaving the editor.
• Saving and committing. Typora only writes the Markdown file; the commit-to-git step is done outside Typora — via the GitHub Desktop client, a terminal, or an IDE. For non-technical users this is usually the only friction point; the project maintainers can do the commit on a contributor’s behalf when needed.
• Licence. Typora is a paid commercial product (modest one-off licence per user). Free alternatives that work for read-only viewing or light editing: VS Code with the built-in Markdown preview, Obsidian (free for non-commercial use), or GitHub’s web editor.

4. Way of Documenting

The CTN architecture follows two complementary documentation frameworks: arc42 for the chapter structure and C4 for the way components are described at different abstraction levels.

arc42

The thirteen-chapter arc42 template (01-introduction, 02-constraints, …, 13-roadmap) is the table of contents of docs/arc42/. Every architectural concern has a home in one of these chapters, which keeps the documentation discoverable.

C4 Model

The C4 model is a lightweight visual and verbal language used to bring consistency to explaining software systems. Its strength is the same vocabulary at multiple zoom levels, suitable for both business stakeholders and engineers.

Audiences:

• Business stakeholders
• Product managers
• Engineering teams
• Operations teams

Benefits:

• Quick comprehension across all stakeholder levels
• Consistent communication
• Scalable from high-level to detailed views

C4 Abstraction Levels

graph TD
    L1[Level 1: System Context]
    L2[Level 2: Container]
    L3[Level 3: Component]
    L4[Level 4: Code]

    L1 -->|Zoom in| L2
    L2 -->|Zoom in| L3
    L3 -->|Zoom in| L4

    style L1 fill:#e1f5ff
    style L2 fill:#b3e0ff
    style L3 fill:#80ccff
    style L4 fill:#4db8ff

1. Actors

Definition: Those who interact with our systems.

Types:

• Human users (end users, administrators)
• Machine actors (external systems, APIs)

2. Context (Level 1)

Definition: The highest level of abstraction.

Characteristics:

• Shows the system in its environment
• Identifies external dependencies
• Suitable for all stakeholders

3. Containers (Level 2)

Definition: Individual runnable and/or deployable units that make up a system.

Examples:

• Web applications
• Mobile apps
• Databases
• File systems
• Microservices

Note: “Container” in C4 refers to something that executes code or stores data — not specifically Docker containers.

4. Components (Level 3)

Definition: Building blocks that resemble the modules that make up a container.

Characteristics:

• Logical groupings of functionality
• Clear responsibilities
• Well-defined interfaces

5. Code (Level 4)

Definition: Detailed implementation level.

In most situations, this level includes:

• UML class diagrams
• Entity-relationship diagrams
• Sequence diagrams
• State diagrams

5. Tooling

IcePanel

Features:

• Interactive C4 diagrams
• Zoom in and out to the desired level
• Support for “flows” to visualise user and machine interactions
• Collaborative editing
• Version-control integration

Use Cases:

• Context diagrams
• Container diagrams
• Component diagrams
• Flow visualisations
• Stakeholder presentations

Mermaid

Purpose: UML class diagrams, sequence diagrams, flow diagrams, and any other diagram type Mermaid supports — embedded directly inside the Markdown.

Advantages:

• Text-based (code as documentation)
• Version-control-friendly (diffs read like text)
• Easy to maintain — edit the diagram in the same file as the prose
• Renders inline on GitHub, in Typora, in most IDEs, and in static-site generators

Use Cases:

• Sequence diagrams for runtime behaviour
• Class diagrams for detailed component structure
• State diagrams for workflow visualisation

Typora

WYSIWYG Markdown editor for contributors who prefer not to work in an IDE. See §3 above.

---

References

• Repository: https://github.com/Basic-Data-Infrastructure/CNCL-BDI
• C4 Model: https://c4model.com/
• arc42: https://arc42.org/
• IcePanel: https://icepanel.io
• Mermaid: https://mermaid.js.org/
• Typora: https://typora.io
• CommonMark: https://commonmark.org/
• GitHub Flavored Markdown spec: https://github.github.com/gfm/

This document serves as a guideline for CTN architecture documentation.