Skip to content

Architecture (arc42)

SailEver's architecture documentation follows arc42, the 12-section template for software architecture. This folder is the map: it says how the system is built and why, and it links to the places where each fact lives (the specs, the ADRs, the infra map). It never copies them: one place per fact still holds.

# Section State
1 Introduction and goals complete
2 Constraints complete
3 Context and scope complete, with diagrams
4 Solution strategy complete
5 Building block view complete, with diagrams
6 Runtime view complete, with diagrams
7 Deployment view complete
8 Cross-cutting concepts complete
9 Architecture decisions complete
10 Quality requirements complete, 7 goals and 12 scenarios
11 Risks and technical debt complete, 15 rated risks
12 Glossary complete

Rules for keeping it arc42

  1. A change that touches a building block, a runtime flow, a quality goal or a decision updates its section here (or adds an ADR) in the same piece of work. /spec-update asks the four questions.
  2. Every section has a Last reviewed: date. mise doccheck warns when it is missing or older than 180 days.
  3. Every ADR is listed in section 9. mise doccheck fails when one is missing. New ADRs (020 and later) name the quality goals they affect.
  4. Link, don't copy. If a fact is in a spec, link to the spec.
  5. A diagram only where a flow needs more than a screen of prose. Mermaid, in the Markdown, so it diffs in git and renders in this viewer and on GitHub.
  6. Structure changes bring an architecture change. A new job, model, controller or migration, or a change to routes.rb, deploy.yml, recurring.yml, queue.yml, infra/ or a workflow, makes mise doccheck gate (the Stop hook) ask for a change under docs/architecture/ or docs/adr/, or an ack with a reason. Sections 3, 5, 6 and 10 must keep a Mermaid diagram, and a ⏳ placeholder must be finished within 45 days of the section's review date.
  7. The viewer is generated. mise docs shows these pages in the browser; Cloudflare Pages builds the same site. No HTML is committed (the infra map is the one exception).