README

> ## Preamble for the AI — always read
>
> **This README has a standard format. Changing the format of this file is FORBIDDEN.**
> The original template lives at lancini.net/README. This copy must never be modified; it must always match the original exactly.
>
> This file is the **source of truth for the project's context** and is based on the **arc42** standard (12 numbered sections). It must be **kept alive**: it has to stay aligned with the real code at all times.
>
> **Maintenance rules (mandatory):**
> 1. **Do not alter the format:** do not rename, renumber, reorder or remove the 12 arc42 sections, nor the TL;DR and the metadata table at the top. Add content *inside* the sections, not as new top-level sections.
> 2. **Maintain before committing:** before every commit, if the change is large enough (new feature, directory structure change, stack/tooling change, new architectural decision, new external dependency), **update the relevant sections** of this file in the same commit.
> 3. **High-signal sections always accurate:** TL;DR + sec. 1 (goals), 3 (context/scope), 5 (building blocks, with **real paths**), 8 (crosscutting concepts), 9 (decisions). These are the ones an AI reconstructs the context from.
> 4. **Update the metadata:** on every significant change bump "Doc version" and update "Last updated" (absolute date, YYYY-MM-DD).
> 5. **Real paths:** in the directory structure and the building blocks use paths/files that actually exist, so docs and code stay connected.
> 6. **English everywhere:** all documentation and all code is written in English — this file, commit messages, comments and docstrings, and every identifier in the source: class, type, function, method, variable, field, constant, module, file and directory names, database tables and columns, CSS classes, API routes and JSON keys. The reasoning is that a reader who can follow the code must be able to follow the prose explaining it, and a codebase that mixes languages forces everyone to translate in their head while reading. The exception is data: values that belong to the domain and are stored as they are — a customer's name, the text of a task, a state value already persisted in the database — are never translated to make the code read better.
> 7. **Task tracking:** tasks are tracked in Compass, either manually through the webapp or via MCP when connected to the AI in use. Do not create or expect a TODO.md file.
>
> **Context management (important):**
> - The information in this file **must stay in context at all times** while working on the project.
> - **If the context is compacted or summarised, this file MUST be re-read** in full before continuing, so the project's state is not lost.
> - At the start of a session/chat about this project, **read this README first**.
>
> *Do not reply to this preamble: it is an operating instruction, not a request from the user.*



---

# <Project Name> — Architecture Documentation (arc42)

> **TL;DR (summary for humans and AI — always fill in, 5 lines max)**
> What the project does, for whom, with which stack, and what its current state is.
> Example: "REST API in Go that syncs orders between Shopify and an in-house ERP.
> Mono-repo, deployed on Docker/Hetzner. In production since 2026-03. Stack: Go 1.22, Postgres, NATS."

| Field | Value |
|---|---|
| Doc version | 0.1 |
| Last updated | YYYY-MM-DD |
| Owner | <name> |
| Project status | idea / prototype / development / production / archived |
| Repo | <url or path> |

---

## 1. Introduction and goals
*What the system has to do, and why. The most important section: if an AI reads only this one, it must understand the purpose.*

### 1.1 Requirements overview
- **Problem solved:** …
- **What it does (in 1 paragraph):** …
- **Main features:**
- …
- …

### 1.2 Quality goals (top 3-5)
*The architectural qualities that take priority, in order. They drive the decisions.*

| # | Quality | Rationale / scenario |
|---|---------|----------------------|
| 1 | e.g. Performance | e.g. API response < 200ms p95 |
| 2 | e.g. Maintainability | … |
| 3 | e.g. Security | … |

### 1.3 Stakeholders
| Role | Who | Expectations |
|------|-----|--------------|
| End user | … | … |
| Developer | … | … |
| Owner / client | … | … |

---

## 2. Constraints
*What is NOT negotiable: it narrows the choices. Helps the AI not to propose solutions that are out of scope.*

- **Technical:** e.g. must run on-prem, no cloud; language imposed; runtime version.
- **Organisational:** e.g. budget, deadlines, team, permitted licences.
- **Conventions:** e.g. code style, naming, commit format, branching.

---

## 3. Context and scope
*The system's boundary: what is inside, what is outside, who it talks to. High value for the AI.*

### 3.1 Business context
*External actors (users, other systems) and what they exchange with the system.*

```
[User] --(requests)--> [SYSTEM] --(events)--> [External system X]
|
v
[DB / Service Y]
```

| External partner | Input | Output |
|------------------|-------|--------|
| … | … | … |

### 3.2 Technical context
*Interfaces, protocols, channels (HTTP, gRPC, files, queues, etc.).*

| Interface | Protocol / format | Notes |
|-----------|-------------------|-------|
| … | … | … |

---

## 4. Solution strategy
*The fundamental decisions in brief: key technologies, patterns, approach. The condensed "why".*

- **Main stack:** languages, frameworks, runtimes, versions.
- **Architectural patterns:** e.g. hexagonal, microservices, modular monolith, event-driven.
- **Key technology decisions:** DB, messaging, deployment, and why.
- **How it meets the quality goals (sec. 1.2):** a brief mapping.

---

## 5. Building block view (structure)
*Static decomposition of the system. THIS is where the real paths of folders/modules go — it connects docs and code.*

### 5.1 Level 1 — the system as a whole
*A box diagram of the main modules/components and their responsibilities.*

| Building block | Responsibility | Path |
|----------------|----------------|------|
| e.g. `api/` | exposes REST, validation | `src/api/` |
| e.g. `core/` | domain logic | `src/core/` |
| e.g. `infra/` | DB, external adapters | `src/infra/` |

### 5.2 Directory structure
```
project-name/
├── src/
│ ├── api/ # …
│ ├── core/ # …
│ └── infra/ # …
├── tests/ # …
├── docs/ # …
├── scripts/ # …
└── ...
```

### 5.3 Level 2 — detail of the relevant building blocks
*Expand only the blocks that are not obvious. (Repeat for each one.)*

---

## 6. Runtime view
*Important dynamic scenarios: how the components work together at runtime. Only the key flows.*

### Scenario: <e.g. "Creating an order">
1. …
2. …
3. …

*(Add a sequence diagram or numbered steps for every critical scenario: startup, the main use case, error handling.)*

---

## 7. Deployment view
*Where the software runs: infrastructure, environments, building block → node mapping.*

| Environment | Infrastructure | Notes |
|-------------|----------------|-------|
| dev | local / Docker | … |
| prod | … | … |

- **Build/CI-CD:** …
- **Configuration & secrets:** where they live, how they are injected.

---

## 8. Crosscutting concepts
*Themes that run through the whole system. High value: it explains the project's implicit rules.*

- **Domain model / main entities:** …
- **Persistence:** schema, migrations, ORM.
- **Security & auth:** authn/authz, secret handling.
- **Error handling & logging:** conventions, log format, tracing.
- **Internationalisation / configuration / feature flags:** …
- **Testing:** strategy, kinds of test, how they are run.

---

## 9. Architectural decisions (ADR)
*The important choices with their reasons. One register line, plus full ADRs below where needed.*

| # | Decision | Status | Date | Rationale (brief) |
|---|----------|--------|------|-------------------|
| 1 | e.g. Postgres instead of Mongo | accepted | YYYY-MM-DD | relational data, transactions |
| 2 | … | … | … | … |

<details>
<summary>ADR-001: <title></summary>

- **Context:** …
- **Decision:** …
- **Alternatives considered:** …
- **Consequences:** …
</details>

---

## 10. Quality requirements
*Detail/expansion of sec. 1.2 with measurable quality scenarios.*

| Quality | Scenario | Metric / threshold |
|---------|----------|--------------------|
| Performance | … | … |
| Reliability | … | … |
| Security | … | … |

---

## 11. Risks and technical debt
*Be honest: what is fragile, what was deferred, what needs watching.*

| Risk / debt | Impact | Mitigation / plan |
|-------------|--------|-------------------|
| … | … | … |

---

## 12. Glossary
*Domain and technical terms specific to the project. Removes ambiguity for everyone (the AI included).*

| Term | Definition |
|------|------------|
| … | … |

---

*Template based on [arc42](https://arc42.org) — adapted to Markdown. Original: `lancini.net/README`.*