ArgusB Lang's
Memory
Architecture decision record 0004 proposed

Store decisions as records inside the platform

Records are first-class platform data rather than files in a repository, because the assistant that reads and drafts them needs somewhere to look.

  • Memory
  • Architecture
  • Argus

2 min read · 498 words

Context01

The forces at the time

Decisions in this system span things that do not share a repository: switch configuration, container definitions, device firmware, and cloud settings. A record explaining why a trunk allows four VLANs has no natural home in any codebase, and a record that lives in the wrong repository is a record nobody finds.

Argus is specified to read existing records and draft new ones. That requires a queryable store with real identifiers, statuses, and relationships — not a directory of files whose structure is a convention rather than a schema.

This record is marked proposed . The store does not exist yet; records are currently written by hand in the shape it would take. The ones on this site are those records.

Decision02

What was chosen

Model decision records as rows in the platform database, exposed through the platform API, with the same lifecycle rules a file-based process would follow: records are immutable once accepted, and a change is a new record that supersedes the old one rather than an edit.

Every record carries a number, a status, its context, decision, alternatives, and consequences, and may link to the systems it concerns. Records drafted by Argus land as proposed and are attributed to the assistant; only a person moves a record to accepted .

The store must be exportable to plain text. If the platform is unavailable, the records must still be readable — a decision history that requires the system it documents to be running is not a decision history.

Alternatives03

What else was considered

Markdown files in a repository
The conventional answer and a good one for a single codebase. Rejected here because the decisions span infrastructure, hardware, and cloud configuration with no shared repository, and because filesystem conventions are not a schema an assistant can rely on.
A wiki
Rejected. Wikis encourage editing in place, which destroys the immutability that makes a decision history worth keeping.
Issue tracker entries
Rejected. Issues are closed and forgotten by design; decisions need to stay visible long after the work is done.
Records in the platform with no export
Rejected. Creates a history that is unreadable during exactly the incidents when it is most needed.
Consequences04

What follows

Gained

  • One place to look, regardless of which layer a decision concerns.
  • Records are queryable by status, tag, and the system they relate to.
  • The assistant has a defined target for drafting and retrieval.
  • Supersession is enforced by the model rather than by convention.

Paid for

  • Writing a record now depends on the platform being available.
  • A database is a heavier home for prose than a text file, and the export path has to be maintained or it will rot.
  • Records become platform data, which puts them inside the backup story — and makes an untested restore a documentation risk as well as a data one.
  • A schema for prose will be wrong at least once and will need migrating.

Records are immutable once accepted. A change supersedes this one rather than editing it.

Related05