WordloopArchitecture Decision Records
The append-only log of significant, hard-to-reverse decisions — and the debt each one carries.
Architecture Decision Records
An ADR is how we remember why. Code shows what we built; commit history shows when it changed; ADRs show which options we rejected, what tradeoffs we accepted, and what debt we took on. The log is append-only: once an ADR is accepted, it is never edited — only superseded.
Why ADRs matter on this team
Two years from now, an engineer — or an agent — will look at a piece of Wordloop and ask "why is this like this?" The answer lives in the ADR. Without it, every design decision regresses to "this is how it was when I got here," and the team loses the ability to challenge decisions on their merits because the merits have been forgotten. We write ADRs for decisions that will be expensive to reverse and decisions that will surprise a reader who does not share our context.
Statuses
| Status | Meaning |
|---|---|
| Proposed | Authored but not yet accepted. Under discussion. |
| Accepted | Current, in force. |
| Rejected | Considered and declined, with reasoning. |
| Deprecated | No longer applicable, but historically important. |
| Superseded | Replaced by a later ADR (which links back). |
Log
The catalogue populates as decisions are committed. Each entry includes title, status, author, date, and a Principal / Interest / Multiplier debt annotation — see Engineering Principles / Documentation for the model.
Authoring a new ADR? Copy the frontmatter and 7-section structure from any existing ADR in this directory. The title is the decision in plain language; the filename is NNNN-kebab-case-decision.mdx with the next available number.
Documentation Freshness
Review windows, freshness statuses, ownership rules, and stale-document handling for Wordloop documentation.
Postgres with pgvector as the production vector store
We keep embeddings alongside their source rows in Postgres via pgvector rather than running a standalone vector database.