Case pattern | Method
Audit-trail and evidence design for regulated software.
Evidence schema and audit-log architecture for software that needs to support a regulator question, an auditor request, or an internal investigation later. The design choices: what gets logged, what gets retained, what gets indexed, who can read it, who can't, and how long it stays around.
By Solyntra Engineering
When you need an audit trail
Some software can get away with minimal logging. Most business software cannot. If your system handles financial data, personal information, healthcare records, legal documents, or any workflow where a mistake has consequences, you need to be able to answer the question: "what happened, when, and why?"
The questions the audit trail answers
A well-designed audit trail should be able to answer:
- •Who did what, when?
- •What was the state of the record before and after the change?
- •What evidence was used to make a decision?
- •Who approved what?
- •What did the system see at the time?
The schema pattern
We structure audit records around events rather than states. Each event captures:
The actor
Who or what performed the action. This might be a user ID, a system process, an API client, or an AI agent. We capture enough context to identify the actor later even if their account is deleted or renamed.
The action
What was done. A typed event name, not free-text. This makes the log queryable and aggregatable.
The target
What the action was performed on. The entity type, the entity ID, and the state before and after.
The evidence
What information was used to make the decision. This might be the contents of a document, the output of an AI classification, or the data from an external system.
The timestamp
When it happened, in UTC, with enough precision to order events unambiguously.
Retention and access
Audit logs are write-once. They cannot be modified or deleted except by a defined retention process. Access is role-based and logged. The logs themselves are auditable.
Retention periods depend on the regulatory context. We design the schema to support configurable retention, with automated archival and deletion at the end of the retention period.
Querying and reporting
A log that exists but cannot be searched is not useful. We index the fields that matter for compliance queries: actor, target, action type, date range. For larger systems, we build dedicated reporting views that aggregate audit data into the formats regulators expect.
Read another pattern
Method pattern
Designing AI agent workflows humans can trust
Building regulated software?
We can help you design audit trails that hold up to scrutiny.
Book a discovery call