Arc42 — Finnest Architecture Documentation¶
This documentation follows the Arc42 template, a proven open-source structure for communicating architecture to mixed audiences (executives, semi-technical stakeholders, engineers, auditors). Each section serves a distinct question:
| # | Section | Answers the question |
|---|---|---|
| 1 | Introduction & Goals | What is Finnest, why does it exist, and what must it deliver? |
| 2 | Constraints | What external rules (legal, organisational, technical) shape the architecture? |
| 3 | System Context | Who uses Finnest, and what does it talk to on the outside? (C4 Level 1) |
| 4 | Solution Strategy | What are the core architectural moves that make Finnest work? |
| 5 | Building Blocks | What are the major parts of the system? (C4 Level 2 + 21 OTP apps) |
| 6 | Runtime | How do the parts cooperate when things actually happen? |
| 7 | Deployment | Where does Finnest run, and what does the production picture look like? |
| 8 | Crosscutting Concerns | Which concerns touch every part — auth, tenancy, events, observability? |
| 9 | Architecture Decisions | Why were specific technology and structural choices made? (Index of ADRs) |
| 10 | Quality Requirements | What quality attributes must Finnest guarantee — performance, security, compliance? |
| 11 | Risks & Technical Debt | What is known to be risky or imperfect? |
| 12 | Glossary | What do the terms mean? |
How to read this documentation¶
- First visit? Start at 1. Introduction & Goals and read straight through to 3. System Context. That's ~15 minutes and will give you the shape of the system.
- Looking for a specific decision? Jump to 9. Architecture Decisions or the full ADR index.
- Want to understand a specific domain? Go to 5. Building Blocks, pick the module, follow its link.
- Need the business-level pitch? 1. Introduction & Goals is deliberately jargon-light.
- Engineer onboarding? Read 1 → 3 → 5 → 8, then dive into the architecture companions.
Sections marked STUB at the top are placeholders — the canonical content lives elsewhere in the planning repository; the stub explains where to find it.