Learning goal: distinguish diagnostic application logs from evidence of a business operation and choose an architecture for a reliable audit trail.

Fictional educational scenario

A payment system lets a user change the destination account. The user sees a confirmation, but after an incident the team only has an HTTP 200 log. It cannot establish who authorized the change, what the previous and new states were, or whether a payout used the new account. An HTTP status is not proof of authorization or a durable business transition.

Three architecture options

  1. Application logs: inexpensive and useful for troubleshooting, but rotation, redaction and incomplete delivery weaken evidential value.
  2. Audit event in the same transaction: records the business fact together with the state change, offering stronger consistency at the cost of explicit data modeling and access controls.
  3. Separate audit event stream: scales ingestion and retention, but asynchronous delivery without a transactional outbox can lose events. Queue acceptance is not the same as durable evidence.

Architectural decision

For operations requiring a defensible audit trail, persist a semantically immutable business audit record atomically with the state transition or through a transactional outbox. Capture the operation identifier, actor and authentication context, action, outcome, server-side timestamp, object version and correlation identifier. Minimize personal data; use references or masked values where appropriate. Separate privileges for performing operations, reading audit records and changing retention policies. Verify integrity controls, access restrictions, time synchronization and retention periods. Do not claim tamper-proof storage without supporting evidence.

Five acceptance tests

  1. A successful state change produces exactly one logical audit fact even when the request is retried.
  2. A rolled-back transaction never produces a false “completed” audit fact.
  3. A broker outage does not lose events held in a transactional outbox; delivery resumes with deduplication.
  4. An unauthorized actor cannot read or alter audit history; attempts are monitored.
  5. Reviewers can reconstruct the sequence of decisions and correlate them with the operation without exposing unnecessary sensitive data.

Architect's question: can you demonstrate not only that the API returned success, but also who changed state, when it happened and how durable evidence was established?

Primary references