Architecture decisions

An architecture decision record is not documentation of a feature. It records a choice that constrains later work, the alternative that was rejected, what the choice costs, and the condition under which somebody would be right to reopen it. The descriptive pages — Architecture overview and Technology stack — say what Omniflow is today. These records say why it is allowed to be that and nothing else. They exist because the expensive mistakes in a platform that moves money are not the ones somebody argued about. They are the ones nobody remembers arguing about, reversed by a contributor who had no way of knowing there was a reason.

​

The records

​

The format

Each record has the same four sections, and they are short on purpose. A record nobody finishes reading constrains nothing.

• Context — the situation that forced a choice, in terms that were true at the time.
• Decision — what was chosen, stated so that a reviewer can tell whether a pull request violates it.
• Consequences — what this costs, including the things that are now harder. A record listing only benefits is advocacy, not a decision.
• Revisit when — the observable condition that would make reopening this correct. “When it becomes a problem” is not one; “when a second installation has to share the job queue” is.

Every record carries a status. Accepted means it constrains current work. Superseded by NNNN means a later record replaced it — the original text is never edited to match the new decision, because the reasoning that was wrong is the part worth keeping.

​

When to add one

Add a record when a change would be expensive to reverse and its reasoning is not visible in the code that results from it. In practice that means: a new durable store, a new external dependency in the request path, a change to who owns a category of data, a new trust boundary, or the removal of a guard that something else assumed. Do not add one for a library swap, a refactor, or a decision whose rationale a reader can recover from the diff. AGENTS.md names two changes that require an accepted record before they can be made at all: introducing a message broker, and adding a dependency-injection framework. The mechanics — file location, the Russian mirror, and the navigation entry — are the same as any other page and are described in Documentation. Number the file with the next unused four-digit prefix; numbers are never reused, including by a record that was superseded.

​

Related