Architecture Decision Records on Doby Baxter Computing

ADR-012: Check Generated Code Against Its Cited Rules, Not Just Its Citations

Sun, 13 Sep 2026 00:00:00 +0000

Context

A system that answers from a rule corpus can cite the rules it used, and citation is commonly treated as sufficient evidence that an answer is grounded. It is not. A citation proves a rule was retrieved and named. It proves nothing about whether the code beneath it obeys that rule.

Nexa is a local, offline assistant that answers Odoo, TypeScript and JavaScript validation questions from a schema-validated rule corpus, running entirely on the user's own hardware. The first version is finished, and this record captures the verification decision that gives it its shape.

ADR-010: Enforcing Data Invariants at the Persistence Boundary for Consistent Data Integrity

Tue, 08 Sep 2026 00:00:00 +0000

Context

A framework like Odoo exposes one stored model through many write paths: the form UI, ORM create() and write(), CSV and Excel import, and remote calls over XML-RPC, the API, and DCI. Each of these paths reaches the same database rows, but they do not share the same guards.

A validation hook attached to the form (@api.onchange) runs only while a user edits in the UI. Every other path (import, RPC, direct ORM) sails past it. This means a rule that feels enforced, because it works when you click through the form, can be silently absent everywhere else.

ADR-011: Fitness for Purpose: Essential Properties for System Evaluation and User Outcomes

Tue, 08 Sep 2026 00:00:00 +0000

Context

The earlier decisions in this series each answer a narrow question: where a validation belongs, which layer owns an invariant, what a component is allowed to assume about the data reaching it. Each one is a local judgment about correctness at a boundary.

Sitting above them is a question those decisions do not answer on their own. A system can satisfy every local rule, run every component as designed, and still fail the person it exists for. A service can have a portal, a workflow, a set of criteria, a budget, and staff, and process a high volume of cases through all of it. None of that establishes that it is doing what it was built to do. A system existing is not the same thing as a system working.

ADR-001: Validate Configuration Before Execution

Sun, 23 Aug 2026 00:00:00 +0000

Context

Configuration is an input to software systems, but configuration errors are often discovered only after execution has already begun. This can lead to confusing failures, partial execution, difficult-to-diagnose behavior, or invalid system state.

For systems where configuration controls execution behavior, configuration should therefore be treated as an input that requires explicit validation rather than something that can be assumed to be correct.

Problem

If invalid configuration is allowed to reach the execution layer, the resulting failure may occur far away from the original mistake.

ADR-002: Validate LLM Workflow Topology Before Execution

Sun, 23 Aug 2026 00:00:00 +0000

Context

An LLM workflow is a directed graph: steps are nodes, and the transitions each step permits are edges. Structural mistakes in that graph, such as a transition to a step that no longer exists, a step with no way out, or a cycle that can never terminate, are present the moment the workflow is written. They do not depend on model output or user content.

Despite that, these errors usually surface only at runtime, in production, minutes into a real conversation, when a step hands off to a target that was renamed or loops until something times out.

ADR-003: Gate Irreversible Actions on Provable Eligibility, Not Navigation

Sun, 23 Aug 2026 00:00:00 +0000

Context

Many workflows collect answers across many steps and end in an action that cannot be undone: a non-refundable payment, a submission, a provisioning call. A real-world post-mortem motivates this record. A http://GOV.UK passport application asked, early on, whether the applicant held a required certificate. The applicant answered "No", which quietly made the whole application invalid, yet the form behaved exactly as it did for every other question and walked the applicant all the way to a non-refundable payment, without ever acting on the answer it had held since near the start.

ADR-004: Test External Source-of-Truth Invariants at the Seam

Sun, 23 Aug 2026 00:00:00 +0000

Context

Most testing advice quietly assumes you own the definition of correct: your code, your tests, your rules, and a failing test means something in your repository changed. Configuration tooling breaks that assumption. Pyxel Config Lab exists to help scientists write YAML that ESA Pyxel, a large and actively-developed framework on its own release cadence, will accept. Pyxel is the source of truth for what a valid config is. The tool only holds a copy of that truth: a bundled JSON schema, a set of tutorial examples, and a mapping of detector types to parameter bounds.

ADR-005: Treat Error Messages as First-Class Outputs

Sun, 23 Aug 2026 00:00:00 +0000

Context

A safety net has two jobs: it has to catch the user, and it has to talk to them when it does. The validation boundaries established in ADR-001, ADR-002, and ADR-004 handle the catching. This ADR concerns the speaking half, which is the part that usually goes unbudgeted.

The speaking half turns out to be the better-researched of the two, and the research is firm. People do read error messages: an eye-tracking study of developers (Barik et al.) found they allocate roughly a quarter of their visual attention to error text, and that reading a message is comparable in difficulty to reading source code. The message is not a footnote to the work, it is work imposed on the reader. Rewriting cryptic errors into enhanced ones (Becker et al.) reduced errors overall and, notably, reduced repeated errors, the signature of someone stuck in a loop, though the literature also shows that prettier wording alone is not the mechanism. Traver's HCI analysis frames the message as the primary interface between the system's internal state and the user's mental model. Later work shows readability is relative to the reader's experience. Nielsen's ninth heuristic (help users recognize, diagnose, and recover) and fifth heuristic (prevent the error in the first place) have held since the 1990s.

ADR-006: Own the Telemetry Namespace for Non-Model GenAI Systems

Sun, 23 Aug 2026 00:00:00 +0000

Context

The LLM Workflow Router is a topology-enforcement layer, not a model-selection router. Given structured metadata about an interaction, it answers one question, "is this workflow transition permitted", independently of model choice or content. It validates workflow topology at load time, enforces invocation limits, and returns one of three terminal decisions: PROCEED, REFUSE, or PAUSE. Its defining property for instrumentation is that it is content-blind: it never sees a prompt, never calls a provider, and never generates a token.

ADR-007: Reconstruct Ranked Attack Paths With Explicit Confidence, Not Binary Detection

Sun, 23 Aug 2026 00:00:00 +0000

Context

In modern cloud incident response there is often nothing to detect in the old sense. Attackers increasingly log in rather than break in: a large share of recent detections are malware-free, with valid-account abuse behind a significant fraction of cloud incidents. Detection tells you that something happened, but rarely how: which account was really patient zero, which token was replayed, which consent grant opened the door, and in what order.

ADR-008: Design API Endpoints That Degrade Without Breaking the Frontend

Sun, 23 Aug 2026 00:00:00 +0000

Context

A full-stack app shows one place, the Sheffield Cholera Monument, at two scales at once: a satellite vegetation view from orbit and a centimeter-scale ground model. The backend is a FastAPI service that authenticates against the Copernicus Sentinel Hub, pulls the newest real Sentinel-2 scene over a bounding box, computes NDVI, and pins a satellite marker to the point in orbit where the satellite passed closest to the monument for that scene. It depends on external systems it does not control: the Copernicus APIs and a live Celestrak orbital-elements feed.

ADR-009: Social Resource Floor as a Contracts-First Coordination Layer Owned by No One

Sun, 23 Aug 2026 00:00:00 +0000

Context

Delivery systems for social protection already exist and are strong: OpenSPP orchestrates programs and registries, OpenG2P provides delivery rails, and OpenCRVS handles civil registration. What is missing is an open, shared layer above them that coordinates one person's whole survival floor across many providers and many resource types at once, so help can find a person regardless of which organizations happen to serve them.

The Social Resource Floor is a blueprint for that missing layer. The first version is finished, and this record captures the architectural decisions that give it its shape.