Architecture and Decisions

Architecture and decisions

This page is a map to the documents that own these facts, not a copy of them. One home per kind of fact is the rule this repository runs on, and a fact repeated in four files is a fact that will be updated in three.

Where each fact lives

Document	Owns
docs/architecture/ARCHITECTURE.md	Crates, modules, sizes, seams
docs/product/MENU_MAP.md	Every menu row and its state
DECISIONS.md	The ADR index, and every lesson learned
docs/decisions/ADR-*.md	One decision each, with its reasoning
ROADMAP.md	Phase status, and what is blocked on what
docs/governance/	The gate, the definition of done, the work model
README.md	What works today, for a reader who has never seen the project
specs.md	The original specification. Historical -- several sections describe things since removed

The shape, in five sentences

A Slint front end (bp-ui) over fifteen library crates. bp-ui connects and displays; it never decides what a feature should do. bp-platform isolates everything the two operating systems disagree about, and takes the platform as a parameter rather than a cfg, so each leg of the gate executes the other's rules. bp-editor holds a rope, so an edit costs what it changes and scrolling costs what is on screen. Nothing anywhere reaches the network or runs a program.

The traps, named

CLAUDE.md names them and DECISIONS.md explains each. In short:

1. A function reading the real profile directory means cargo test writes there.
2. Code taking a Platform parameter must not let std::path answer for it.
3. A claim in a comment is not a property of the code. What would fail if this stopped being true? If nothing, it is a wish.
4. Two claims about the same function coexist for as long as nothing asks.
5. "Unique" must mean no earlier run either.
6. A claim in the record is not a property of the repository. A question that has waited several sessions should have its premise checked before it is asked again.
7. A round trip through one build says nothing about another build.

Trap 6 is the one this project has been caught by twice, most recently by ADR-0073: an accepted ADR rested on GitHub Actions is not available to this project, and one API call disproved it.

An ADR whose reasoning rests on an external fact should name the command that would test it.

The decisions a newcomer meets first

ADR-0001	Windows 10, Windows 11 and Linux are equal targets
ADR-0006	Core editing never depends on cloud or AI services
ADR-0016, ADR-0073	The local gate is authoritative; hosted CI judges pull requests
ADR-0018	Two editor surfaces, and why the custom one is opt-in
ADR-0055	Unsigned releases, and self-signing refused outright
ADR-0057	This product executes nothing
ADR-0059--ADR-0064	The reduction: what was removed to make this Lite, and why
ADR-0067	No installer
ADR-0071	GPL-3.0-only, and why not -or-later
ADR-0072	macOS declined, with what it would cost
ADR-0074	The product is BachelorPad+ Lite
ADR-0075	One documentation source, four destinations
ADR-0076	The website: what it may collect, and why it does not follow af-site on analytics
ADR-0077	Reporting a problem composes a document, because this product opens no browser
ADR-0078	Three unmaintained dependencies accepted by name, never as a category

Writing an ADR

One decision per file, numbered in sequence, with Status, Date and the ADRs it depends on. Context, Decision, Consequences, and -- the part this project actually reads -- The lesson: the general form of the mistake, so the next person recognises its shape somewhere else.

Add a row to DECISIONS.md, which is the index and the one home for lessons.

A decision that removes a planned feature is a real result and needs no permission. The ADR is the point: the reasoning is worth more than the row would have been.

---

This page is generated from docs/developer/04-architecture-and-decisions.md and edits made here will be overwritten. Change the source and open a pull request.