Subsystem 01
Audit log interceptor
Captures user actions, IP addresses and state diffs in middleware
Typical stack
FastAPI / Node.js middleware
Reference architecture
Tamper-evident audit logging engine for enterprise SaaS
An audit logging platform that makes tampering detectable with cryptographic hash chains and write-once storage, with search and export built for auditors.
Design constraints
What the design has to hold to
Targets for the scenario this reference is sized for. A real engagement starts by replacing them with your own numbers.
- 01Tamper-evident: altering any past record breaks the hash chain
- 02Audit writes kept off the main database's transaction path
- 03Log fields and retention mapped to SOC 2, HIPAA, FedRAMP and ISO 27001 requirements
- 04Full-text search and export across 5 years of history
Component topology
System components and technologies
Subsystems with separate responsibilities, clear contracts between them and storage that scales on its own. The stack named for each is typical, not mandatory.
Stack topology
Tamper-evident audit logging engine for enterprise SaaS
Illustrative reference architecture
- 01
Audit log interceptor
Captures user actions, IP addresses and state diffs in middleware
FastAPI / Node.js middleware
- 02
Hash chaining service
Links each event's SHA-256 hash to the previous one and seals blocks with a Merkle root
Go worker service
- 03
Immutable storage tier
Write-once-read-many (WORM) storage that prevents deletion
Amazon S3 with Object Lock
- 04
Compliance search engine
Fast investigation and export queries for auditors
ClickHouse / OpenSearch
Subsystem 02
Hash chaining service
Links each event's SHA-256 hash to the previous one and seals blocks with a Merkle root
Typical stack
Go worker service
Subsystem 03
Immutable storage tier
Write-once-read-many (WORM) storage that prevents deletion
Typical stack
Amazon S3 with Object Lock
Subsystem 04
Compliance search engine
Fast investigation and export queries for auditors
Typical stack
ClickHouse / OpenSearch
Data lifecycle
End-to-end data flow
A user performs an action, such as changing a billing tier or viewing a medical record.
Middleware captures the actor ID, timestamp, IP address and a JSON before-and-after diff.
The event is queued in Redis asynchronously, so the user's request returns immediately.
The hash chaining service computes SHA-256(prev_hash + current_event) and seals the block.
Sealed blocks are written to S3 Object Lock and indexed into ClickHouse for auditor search.
Reliability and resilience
Failure modes and how each is contained
Failure mode 01
Audit events lost during a database outage
Mitigation
Buffer events in replicated Redis with persistence enabled until they reach primary storage.
Failure mode 02
Log volume growth
Mitigation
Compress payloads with Zstandard (zstd) and partition ClickHouse tables by month.
Failure mode 03
Tampering by a privileged cloud administrator
Mitigation
Keep S3 Object Lock compliance-mode retention in a dedicated security account, isolated from engineering accounts.
Questions
What teams ask about this design
Each record includes a hash of the previous record, so modifying or deleting any historical entry breaks the chain for every record after it, and verification shows exactly where.
SOC 2 doesn't prescribe a field list, but auditors expect to see who did what, to which resource, when, from where and with what result: timestamp, actor, action, target, source IP and outcome.
Planning a system like this?
Send us your requirements, expected load and budget. We'll reply within one business day with an honest read on the design, and on whether we're the right team to build it.