Building an audit-ready codebase

A system that is easy to audit and a system that is hard to audit rarely differ in how carefully they were built. They differ in four structural decisions, usually made early, usually without anybody framing them as compliance decisions at all.

One: route regulated data through a single access point

The single most useful decision is that reading or writing regulated data cannot happen without passing through code you control.

Every audit implementation that relies on developers adding a log call in the right place fails over time. Not through carelessness, but because there will be several hundred new code paths over three years and some of them will miss it. The version that keeps working is one where the mechanism that reaches the data is the mechanism that produces the trail, enforces the permission, and applies the retention rule.

Concretely: a data access layer that owns regulated entities, through which all reads and writes go. Direct database access from arbitrary application code is prevented rather than discouraged, ideally at the credential level so it is enforced rather than agreed. New code paths inherit the controls automatically, because they cannot reach the data any other way.

This is straightforward at the start and expensive once four hundred call sites exist, which is why it belongs first. If you are retrofitting, the intermediate step is to enumerate the paths that bypass the layer and shrink the list deliberately rather than trying to fix everything at once.

A concrete version of the failure this prevents: a support tool is added to help agents look up an account faster, and the fastest way to build it is a direct read against the production database, because going through the access layer would have meant writing an adapter first. That query works, ships, and is never revisited. Two years later a data-access audit walks every code path that touches a customer record and finds this one produces no log entry, because it never passed through the layer that writes the trail. Nobody added it maliciously and nobody skipped a review. The tool was built by someone who needed to solve a problem quickly, and the shortcut was invisible because it worked exactly as intended from the support agent's point of view. That is what "fails over time" means in practice: not a single bad decision, but an accumulation of reasonable ones made without the constraint in place.

Two: capture decisions as immutable records

Anything the system decides that affects a person, and anything it does to regulated data, should produce a record written at the time, containing enough to reconstruct what happened.

The critical property is that this cannot be added retrospectively. Analysis can be added later. Interfaces can be built later. The data itself, if you did not capture it, is simply gone, and no amount of engineering effort recovers it. That asymmetry is why decision capture deserves to be an early decision rather than a later one.

What to capture depends on sector, and the pattern is consistent: the inputs as values rather than as references to records that will change, the version of whatever logic produced the outcome, the outcome, the actor, an unambiguous timestamp, and the interface used. For model-driven decisions add the factor attribution computed at decision time, for the reasons on explainability and adverse action.

Make the store append-only, and make it unwritable by the application's ordinary credentials. A record the audited party can modify is not evidence.

The edge case worth planning for is the correction. Decisions get made on wrong data, logic has bugs, and a genuinely incorrect record will need to be fixed at some point. The instinct is to update the row, which destroys the immutability that made the record trustworthy in the first place. The pattern that preserves both properties is to never edit a record, and instead write a new one that supersedes it, with an explicit reference back to the record it corrects and a stated reason. The history then shows both what was originally decided and what correction was made and why, which is a stronger position in an examination than a record that looks like it was always right, because a record that has clearly never needed correcting over years of operation invites the question of whether corrections were happening outside the system that was supposed to capture them.

Three: trace checks to provisions

Each compliance check carries a reference to the specific provision it exists to satisfy, placed next to the assertion in the code.

The payoff is that coverage becomes visible. Put the obligation list beside the suite and the obligations with nothing attached stand out, which is the question everybody wants answered and almost nobody can answer. Without the trace you are inferring intent from test names, and nobody does that thoroughly enough to trust.

The second payoff is maintenance. When a provision is amended, the affected checks can be found with one search rather than a long search through a suite nobody has read in a year.

The third, and the one that matters during an examination, is that it lets you give someone a clear list. "Here is the provision, here is the assertion that enforces it, here is every commit it ran against" is a fundamentally different conversation from walking someone through an architecture diagram.

Four: retain long enough

Three things need retention aligned to the obligation rather than to a tool's default: the decision records, the check results, and the artefacts the records reference.

The check results are the ones teams lose. A CI system commonly discards build records after a few months, and that setting is one line of configuration nobody has a reason to look at until an examiner asks about a release from eighteen months ago. The evidential value of a check suite is in its history, as covered on using evals as compliance evidence, and a short retention window throws away exactly the part that cannot be reconstructed.

The artefacts are the ones teams do not think of. A decision record naming model version 47 is incomplete if model version 47 was deleted, because you can no longer say what it would have done. Retaining old artefacts feels like clutter right up to the moment it is the only thing that would have helped.

This is also where the sector guides on this site diverge in specifics while agreeing on the structure. A financial firm's recordkeeping obligation names a defined multi-year retention period for the record itself. A healthcare obligation may separate the retention of the record from the retention of the audit trail describing who accessed it, with different periods attached to each. Reading the obligation carefully enough to notice that it names two different things with two different clocks, rather than assuming one retention setting covers both, is exactly the kind of gap the specification exercise on compliance is a specification problem is built to catch.

What this costs

Being honest about it: the single access point costs design time early and saves substantially later. Decision capture costs storage and some computation on every decision, and the computation is the part people object to, particularly factor attribution. Tracing costs almost nothing. Retention costs storage.

The largest cost is the single access point if you are retrofitting, and it is the one worth paying, because every other control depends on there being a place to put it.

The thing to weigh it against is not zero. It is the cost of the alternative, which is an examination or an incident where the answer to a direct question is that the system cannot tell you. Our piece on the real cost of shipping unverified code covers the general form of that trade-off.

Where to start on an existing system

You will not retrofit all four at once, and trying produces a project that stops. The order that works:

Start with decision capture, because it is the one where every day of delay permanently loses data. Even a partial implementation covering the highest-consequence decisions starts accumulating a record immediately.

Then trace whatever checks you already have, which is cheap and immediately shows you how much of your obligation list is unenforced.

Then fix retention, which is usually a configuration change and occasionally a storage cost conversation.

Then work on the single access point incrementally, starting by enumerating the bypass paths rather than by building the layer, because knowing how many there are determines whether this is a quarter of work or a year.

If you want help sequencing that for an existing system, get in touch.