arc42

arc42 is a free, open template for documenting software architectures, created by Dr. Peter Hruschka and Gernot Starke in 2003. It is the de-facto standard for software architecture documentation in the German-speaking IT industry and is used internationally as a vendor-neutral, technology-agnostic structure.

Authoritative source	https://arc42.org/overview/
Maintainers	Dr. Peter Hruschka, Gernot Starke (Aim42)
Local home in the kit	`template/docs/arc42/`
Slot in pentaglyph	#1 of 5 — the architecture spine

What problem does arc42 solve?

Architecture docs typically suffer one of three failure modes:

Empty — no architecture doc exists; the design lives only in the heads of senior engineers.
Bloated — a 200-page Word document nobody reads; updated once at hand-over and never again.
Improvised — a single README.md that grew topics ad-hoc; no shared structure between projects.

arc42 fixes mode 3 by providing a 12-section template that names every architectural concern once and gives it a fixed home. Sections you don’t need stay empty stubs (the structure itself is informative).

The 12 sections at a glance

#	Section	What goes in it
1	Introduction & Goals	What the system does and its 2-3 top-priority quality goals
2	Constraints	Technical / organisational / political constraints that limit choices
3	Context & Scope	What systems / actors integrate with this one; what is out of scope
4	Solution Strategy	The big-picture technical choices and why
5	Building Blocks	Static decomposition (links into `detailed-design/` for L2+)
6	Runtime View	Sequence diagrams for important scenarios
7	Deployment View	Where the system actually runs
8	Crosscutting	Concerns that span modules: security, observability, error model, i18n
9	Decisions	MADR ADRs — the why behind technical choices
10	Quality	SLOs, KPIs, performance / reliability targets
11	Risks	Technical debt, known fragilities
12	Glossary	Domain vocabulary

How pentaglyph uses arc42

Pentaglyph maps each of the 12 sections to a directory under template/docs/arc42/:

template/docs/arc42/
├── 01-introduction-and-goals/
├── 02-architecture-constraints/
├── 03-context-and-scope/
├── 04-solution-strategy/
├── 05-building-blocks/        ← links into ../detailed-design/
├── 06-runtime/
├── 07-deployment/
├── 08-crosscutting/
├── 09-decisions/              ← MADR ADRs go here
├── 10-quality/
├── 11-risks/
└── 12-glossary/

Pentaglyph adds AI-readable README.md files to each directory so an LLM can decide where to place new content with zero project context.

When to use the full template

Minimal profile: fill §1 (Goals), §3 (Context), §5 (Building Blocks), §9 (Decisions). Skip the rest until you have a concrete reason to fill them.
Standard / Full profile: progressively fill more sections as the system grows. arc42 explicitly endorses partial coverage.

When NOT to use arc42

Single-file scripts or throwaway prototypes — overkill.
Pure documentation repositories (use Diátaxis directly).
Codebases that will be deleted in < 3 months.

Authoritative references

Official site: https://arc42.org/overview/
Free PDF / Asciidoc / Markdown templates: https://arc42.org/download
Book (free): arc42 by Example — Gernot Starke & Michael Simons
Maintainer organisation: Aim42 — for architecture improvement methods