How the repository works
One repository, and everything else comes out of it
Your architecture lives in a folder, in files a person can read. Not in a tool, not in a database, not in a hundred diagrams that stopped agreeing with each other two years ago.
Everything below is about that folder: what goes where, who may put it there, and what you get back.
What you already have
Interviews. A spreadsheet someone emailed. A slide deck from a project that finished. Notes from a meeting where three people described the same process differently.
None of it is thrown away, and none of it is cleaned up first. Nor does it have to be converted first: Word, PowerPoint, Excel, PDF, HTML — all of it becomes Markdown on the way in, and anything already written in Markdown or plain text goes in untouched. The original file is kept, with a fingerprint, so anything built on it leads back to the document it came from.
field/ — what you were told
Raw material, exactly as it arrived. An interview stays an interview. A draft stays a draft.
Two people may contradict each other here, and that is not a problem to fix: this folder records what was said, not what is true. What matters is knowing who said it and when, so that anything built on it can be traced back.
codex/ — what you must obey
Laws, regulations, industry standards — and your own policies, which count just as much.
The difference from everything else: you did not write these, and you do not get to adjust them. A regulation is kept as it was issued, word for word. If your model and a regulation disagree, the model is what changes.
knowledge/ — what someone worked out
The step in between. Someone reads five interviews and a policy, works out what they actually mean together, and writes that down — with the sources cited and the date on it.
It is not raw material any more, because a person has made sense of it. It is not the model yet, because nobody has admitted it. Think of it as a good, careful answer to one question, kept where the next person can find it instead of working it out again.
Many teams never need this folder. Keep it if your material arrives faster than you can model it; skip it if it does not.
canon/ — what the organisation says is true
The model itself. One thing per file: a process, an application, a goal, a requirement, each with its own file, its own type, and the dates between which it holds.
This is the only folder whose contents your organisation stands behind. Everything above feeds it; nothing above it is binding.
The gate: a tool proposes, a person admits
A tool can read your material and propose entries at any hour of the night. Nothing it proposes enters the model on its own.
Something becomes part of canon/ only when a person lets it in — and that permission is the pull request your team already uses. Not a committee, not a second system, not a new ceremony. The review you already do is the gate.
operations/decisions/ — why you did it that way
Your team's own record of the choices it made: what was decided, when, and what the alternative was. One file per decision.
These sit beside the model rather than inside it, and the distinction does real work. A decision is a fact about your team. A weakness in the business you are modelling is a fact about the business, and belongs in the model.
What comes out
Diagrams, documents and reports are generated from the model. A capability map, a layered view, a process diagram — three different questions asked of the same content.
So they cannot drift from it, and nobody spends a Thursday bringing a diagram back in line with reality. Delete every generated view and you have lost nothing: run it again.
And one repository is not the boundary
Every project keeps its own repository, with its own model and its own decisions. Joining is one line of configuration.
A scheduled read collects every project's decisions into a single index. It only reads — nothing is written back into a team's repository, and no team has to change how it works to be included. Lose the index and you rebuild it by running the collection again.