Audit Service — Application Logic
Status: populated Owner: TBD Last updated: 2026-04-18 Companion: Service Template · 02 DDD
1. Use Cases (Commands)
| ID | Use Case | Trigger | Actor |
|---|---|---|---|
| UC-AUDIT-01 | Ingest event | NATS message received | System (NATS consumer) |
| UC-AUDIT-02 | Request export | POST /api/v1/audit/exports | Super Admin |
| UC-AUDIT-03 | Process export job | Export worker tick | System (background worker) |
2. Use Cases (Queries)
| ID | Query | Trigger | Actor |
|---|---|---|---|
| UC-AUDIT-04 | Query audit entries | GET /api/v1/audit/entries | Tenant Admin / Super Admin |
| UC-AUDIT-05 | Get single entry | GET /api/v1/audit/entries/:id | Tenant Admin / Super Admin |
| UC-AUDIT-06 | Accounting-of-disclosures | GET /api/v1/audit/disclosures | Tenant Admin / Super Admin |
| UC-AUDIT-07 | Check export status | GET /api/v1/audit/exports/:id | Super Admin |
3. Orchestration Flows
3.1 Ingest Event (UC-AUDIT-01)
3.2 Request Export (UC-AUDIT-02)
3.3 Process Export Job (UC-AUDIT-03)
The export worker runs on a configurable polling interval (default 30 s):
- Query
audit_exportsforstatus = 'queued'; claim one job (UPDATE with optimistic lock). - Set status to
processing. - Cursor-stream matching
audit_entriesrows from PostgreSQL. - Write NDJSON or CSV to object storage under
exports/{tenantId}/{exportId}.{format}. - Generate pre-signed URL (TTL 24 h).
- Update
audit_exports:status = completed,fileUrl,recordCount,completedAt. - Publish
audit.export.completed.
4. Ports
| Port name | Type | Direction | Adapter |
|---|---|---|---|
AuditEntriesRepository | port | outbound | postgres-audit-entries.adapter.ts |
AuditExportsRepository | port | outbound | postgres-audit-exports.adapter.ts |
EventPublisher | port | outbound | nats-event-publisher.adapter.ts |
ObjectStorage | port | outbound | s3-compatible-storage.adapter.ts |
EventSubscriber | port | inbound | nats-jetstream.adapter.ts |
5. Background Jobs
| Job | Schedule | Description |
|---|---|---|
| Export worker | Poll every 30 s | Picks up queued exports and processes them |
| Chain integrity verifier | Daily at 02:00 UTC | Reads audit_entries in order and verifies each chain hash; alerts on mismatch |
6. Error Handling
| Scenario | Handling |
|---|---|
| NATS delivery fails (network) | NATS JetStream retries automatically |
| DB INSERT fails (transient) | NACK the NATS message; NATS will redeliver with backoff: [1s, 5s, 30s, 2min, 10min] |
| DB INSERT fails 5 times | Message moves to audit.dlq; audit.dlq.alert event emitted; platform-admin notified |
Duplicate source_event_id | Idempotently ACK'd; no duplicate entry created |
| Export worker fails | Set status = failed; log error with exportId; surface in Grafana alert |
| Chain verification mismatch | Emit CRITICAL log span; page on-call via Alertmanager |