Decisions

What a decision record is

An architecture decision record, or ADR, is a short file that states one decision and why it was made. In ivralo a decision gets one when it meets three tests:

• it is hard to reverse;
• it would surprise someone who did not know the context;
• it came out of a real trade-off, where the other option had something going for it.

A record is one to three sentences, sometimes with a short list of consequences. It lands in the same pull request as the code that carries it out, so the reason and the change arrive together. Code comments and the guide cite records by number, as in "ADR 0113".

Where they live

The records are in docs/adr/ in the repository, one Markdown file each, named NNNN-slug.md and numbered in the order they were made. There are 169 on main. The repository is private; access is given on request at kemalcalak@gmail.com.

How to read one

---
status: accepted
supersedes: 0051 (the table half; the reference syntax and the announcement stand)
---

# 0056 - The provider list is agno's, discovered, not written - and the embedder is chosen the same way

A model is named ``<package>[.<Class>]:<model>`` where the package is a
directory under `agno.models` ...

• The title is the decision itself, as a sentence. Reading the titles alone gives you most of the design.
• The body says why: what was chosen, what it was chosen over, and what it costs.
• status reads accepted once the decision is taken. A superseded record keeps its status; the record that replaces it is what tells you.
• A record is never edited to change its decision. Reversing one takes a new record that supersedes it, named in its frontmatter or in its first sentence. Often only part of the old record is replaced, and the new one says which part still stands, as above.

So to know whether a decision still holds, look for a later record that names its number. ADR 0051, for example, said that embeddings stay on Ollama; ADR 0056 replaced that half and lets the embedder be any provider, while 0051's rule that a hosted model is always announced still stands.

When a record and the code disagree, the code is what runs. The record tells you what the code was meant to do and why.

The decisions that matter most when you run ivralo

Architecture shows how these fit together, and What leaves the machine follows the privacy decisions through.