Skip to content

Use Cases — Audit Trail Platform (ATP)

ATP is the tamper-evident, multi-tenant compliance backbone for the ConnectSoft SaaS ecosystem. It captures and exposes every meaningful user/system action across services with immutability, isolation, and verifiable integrity—built on DDD, cloud-native patterns, and zero-trust controls.

Purpose & Scope

This document defines the use-case catalog for ATP. Each use case expresses: the business intent, the system responsibilities across Audit.* services, and success criteria that can be verified via APIs, exports, and integrity checks. It targets architects, developers, operators, and compliance/security readers to ensure a shared language and expectations.

Readers & Actors

The platform is used by multiple personas. We group them as Platform actors, Tenant actors, and System actors to keep scenarios consistent and traceable.

Category Actor What they do (in context of ATP)
Platform Architect / CTO Defines boundaries, service responsibilities, and multi-tenant strategy for audit across ConnectSoft services.
Developer / Integrator Emits/consumes audit events via SDKs and APIs; ensures idempotency and correlation headers.
SRE / Operator Operates ATP, validates health/SLOs, handles DLQ & replay, and observes ingestion→query flows.
Compliance / Security Verifies retention, redaction, and tamper-evidence; manages legal holds and export evidence.
Tenant Tenant Admin Configures tenant policies (retention/residency), initiates exports, and reviews audit queries.
End User Generates auditable actions (e.g., login, data access) captured through upstream apps/services.
Billing / Finance Triggers auditable financial events (refunds, invoices) consumed by ATP for evidence.
Support Agent Executes tenant-scoped support actions that must be recorded and queryable.
System Producer Service / SDK Emits canonical AuditRecords through Outbox → Bus (ASB/MassTransit) into Ingestion.
API Gateway AuthN/Z, throttling, version routing for Query/Export/Ingestion edges.
Audit.IngestionService Validates, normalizes, and appends audit records.
Audit.StorageService Multi-tenant append-only persistence (WORM) and retention tiers.
Audit.QueryService Read projections and streaming APIs for retrieval.
Audit.IntegrityService Rolling hash chains and signatures for tamper evidence.
Audit.ExportService Asynchronous eDiscovery exports with signed manifests.
Audit.PolicyService Retention & legal-hold evaluation/enforcement.
Audit.SearchService Full-text and analytical indexing.

Note: These actors map directly to the core microservices and the end-to-end lifecycle from emission to export.

Boundaries & Interfaces (Primer)

ATP integrates through well-defined interfaces and shared foundations:

  • Messaging Bus: MassTransit over Azure Service Bus (Outbox, retries, DLQ).
  • APIs: REST + gRPC entry points exposed via the API Gateway with AuthN/Z, throttling, and versioning.
  • Webhooks: Signed callbacks for policy actions, export completion, and integrity alerts.
  • Observability: OpenTelemetry traces/metrics with Grafana dashboards for end-to-end visibility.

See the Integration Points and Lifecycle diagrams for how producers, the bus, and Audit.* services compose the pipeline.

Jump-starts & Navigation

Pick the path that matches your role and task:

For architecture overviews and component details, start here: → High-Level Design • Components & Services • Events Catalog.

Producer-side Use Cases (How audit is emitted)

Producer flows follow a consistent lifecycle — Outbox → Bus (ASB/MassTransit) → Ingestion → Storage → Integrity/Projections — exposed at the edge via the API Gateway.

Integration foundations: Messaging (ASB/MassTransit), REST/gRPC APIs, signed webhooks, OpenTelemetry.

UC-P1 — Identity login & access decision

Actors Developer/Integrator (producer service), Compliance/Security, API Gateway, Audit.* services.

Intent Record a user login and access decision (allow/deny, scopes, resource) with tenant context for provable non-repudiation and zero-trust evidence.

Preconditions

  • Token issued by ConnectSoft Identity (OpenIddict), tenant-scoped.
  • Required headers present: X-Tenant-Id, X-Trace-Id, X-Idempotency-Key.
  • Producer SDK configured for Outbox + ASB transport.

Main flow

  1. Producer constructs AuditRecord (category=identity, action=user.login, actor/resource metadata) and writes to Outbox.
  2. Message dispatched over Azure Service Bus via MassTransit with correlation headers.
  3. Audit.IngestionService validates schema, tenant, and actor; republishes canonical append event.
  4. Audit.StorageService persists to append-only partition; Audit.IntegrityService extends hash chain and signs batch.
  5. Audit.Query/Search project and index for retrieval; API access enforced at Gateway.

Data & compliance

  • PII fields classified/redacted at field level; data encrypted at-rest/in-transit; signatures prove tamper evidence.
  • Zero-trust controls (workload identity, mTLS) secure intra-service hops.

Observability OpenTelemetry traces from Gateway→Ingestion→Storage; login category KPIs on Grafana.

Failure & retries ASB retries/DLQ; replay is idempotent due to X-Idempotency-Key.

Acceptance

  • Record visible via Query within SLA, with signed integrity block referencing the event.

UC-P2 — Config / FeatureFlag changed

Actors Tenant Admin, Developer/Integrator (Config/Feature service), Audit.* services.

Intent Capture before/after deltas when a configuration or feature flag changes, enabling traceability and policy-aware projections.

Preconditions

  • Config/Feature service emits domain events; uses Outbox + ASB.

Main flow

  1. Producer writes configuration.changed with {path, oldValue, newValue, reason, actor} to Outbox.
  2. Ingestion validates tenant scope and normalizes delta payload.
  3. Storage appends; Integrity seals batch; Query/Search update projections for “effective config” timelines.

Data & compliance

  • Classification applied if values include PII; redaction policies enforced on exports.

Observability Traces link change request → audit append; dashboards show config-change rate and actor distribution.

Acceptance

  • Query returns a diff view per path within SLA; integrity proof covers the batch containing the change.

UC-P3 — Billing refund posted

Actors Billing/Finance app, Producer SDK, Audit.* services, Compliance.

Intent Record a refund with immutable linkage to invoice/payment, enabling financial forensics and compliance exports.

Preconditions

  • Billing service employs transactional Outbox; emits billing.refund.posted.
  • Domain model tracks refundId, paymentId, amount, currency, reason. (Finance modeling pattern.)

Main flow

  1. Refund command commits; outbox writes canonical audit payload (ids, amounts, actor, tenant).
  2. ASB dispatch; Ingestion validates and appends; Storage persists; Integrity signs.
  3. Query/Export surfaces refund timelines and allows signed eDiscovery packages.

Data & compliance

  • Financial PII redaction (e.g., masked PAN last-4) and encryption controls.

Observability Trace links refund command → audit append; compliance SLOs monitored.

Acceptance

  • Export contains refund with signed manifest and integrity references; query shows correlation to original payment.

UC-P4 — Support action on tenant data

Actors Support Agent, Support tooling (through API Gateway), Producer SDK, Audit.* services.

Intent Capture privileged, tenant-scoped support actions (e.g., “reset MFA for user X”), recording who did what, with justification and scope.

Preconditions

  • Access via Gateway with role scopes and rate limits; justification header required (X-Purpose).
  • Producer emits support.action.performed with resource, action, reason.

Main flow

  1. Support tool calls service via Gateway; service writes audit envelope to Outbox with correlation ids.
  2. Ingestion → Storage → Integrity pipeline appends and seals record.
  3. Query/Search projections enable per-resource timelines; access governed by tenant isolation.

Data & compliance

  • Redaction for any sensitive fields; access controlled by tenant-scoped tokens + least privilege.

Observability Support actions tagged and charted; alerts for unusually high privileged actions.

Acceptance

  • Each action retrievable with who/what/why context and cryptographic proof; webhook breach hooks configured if misuse is detected.

Consumer-side Use Cases (query, export, eDiscovery)

Consumer flows rely on Audit.QueryService, Audit.ExportService, Audit.PolicyService, and Audit.IntegrityService, all accessed through the API Gateway with tenant-scoped auth and isolation. These scenarios emphasize safe retrieval, scoped exports, and verifiable evidence.

Actors Auditor/Compliance, API Gateway, Audit.QueryService, Audit.SearchService, Audit.IntegrityService.

Intent Filter and review an actor/resource/time-bounded timeline of events with policy-driven redaction and strict tenant isolation.

Preconditions

  • Tenant-scoped token via Gateway; least-privilege scopes.
  • Query/Search projections available for the tenant.

Main flow

  1. Auditor calls Query API through the Gateway with filters: actor.id, resource.type/id, action, fromUtc–toUtc. Results stream from read projections; full-text terms go through Search.
  2. Returned records include integrity metadata enabling proof verification against the tenant’s hash chain.
  3. Client-side or export-on-demand validation can re-check signatures for a selected window.

Data & compliance

  • Redaction and field classification applied to sensitive values; encryption at rest/in transit.
  • Isolation: queries are partitioned by tenant to prevent cross-tenant leakage.

Observability

  • OpenTelemetry traces expose Gateway→Query→Search latency and result counts for the request.

Actors Compliance/Security, PolicyService, Storage/Integrity, Gateway.

Intent Place a Legal Hold to freeze eligible records for a case and prevent purge, while preserving a full audit of the hold lifecycle.

Preconditions

  • Admin scopes (audit.admin.policy) and justification header (X-Purpose) via Gateway.

Main flow

  1. Compliance places a hold: POST /audit/admin/legal-holds with {caseId, categories, range?, query?, reason}. PolicyService records the hold and emits legalhold.applied.
  2. Retention evaluators re-check purge eligibility, excluding any items covered by the hold; purge/archival actions skip held records.
  3. Releasing a hold uses POST /audit/admin/legal-holds/{holdId}:release; history of applied/released holds remains immutable.

Data & compliance

  • Holds are append-only (never edited in place) and are included in compliance evidence. Webhooks can notify downstream systems of hold placement.

Observability

  • PolicyApplied/retention events and traces surface timing and scope of evaluations.

UC-C3 — eDiscovery export with signed manifest

Actors Auditor/Tenant Admin, ExportService, IntegrityService, Gateway, Webhook consumer.

Intent Produce an eDiscovery export for a defined scope (time/categories/query), with a signed manifest and integrity proofs, then notify consumers via signed webhook on completion.

Preconditions

  • Access via Gateway; background export jobs enabled in ExportService.

Main flow

  1. Client requests an export job (e.g., POST /audit/exports) with scope filters. ExportService enqueues and processes asynchronously.
  2. On completion, ExportService writes a manifest to Blob with counts, hashes, and references to sealed segment proofs.
  3. A signed webhook is sent to the tenant’s endpoint indicating status and a secure download link.

Data & compliance

  • Export observes policy-driven redaction and includes integrity references for third-party verification.

Observability

  • Traces cover Gateway→Export pipeline; dashboards chart job durations and sizes.

UC-C4 — Tenant admin self-serve export (scoped)

Actors Tenant Admin, Gateway, ExportService.

Intent Allow a tenant admin to generate a scoped export (time/categories/query) for their own tenant with platform-enforced rate limits and governance quotas.

Preconditions

  • Tenant-scoped token; export APIs exposed via Gateway.

Main flow

  1. Admin calls POST /audit/exports with tenant-bound filters; Gateway enforces rate limits and authz.
  2. ExportService executes as in UC-C3; export is isolated to the requesting tenant’s partitions.
  3. Completion is announced via export webhook; admin downloads artifact and manifest.

Data & compliance

  • Tenant isolation and redaction policies apply; results are encrypted and signed.

Observability

  • Per-tenant export metrics and request traces visible in Grafana/OTel dashboards.

Compliance, Zero-Trust & Tamper-Evidence Scenarios

These scenarios explain why ATP can be trusted under audit: cryptographic integrity, zero-trust enforcement, breach signaling, and auditable policy execution.

UC-Z1 — Chain verification after incident

Actors Compliance/Security, Audit.IntegrityService, Audit.StorageService, API Gateway.

Intent Verify the integrity chain for a selected time window to detect any mutation and produce cryptographic proof.

Preconditions

  • Integrity blocks and signatures are maintained in the SignatureLedger with rolling hash chains.
  • Tenant-scoped access via Gateway.

Main flow

  1. Investigator picks a time window and requests a verification job (e.g., /audit/integrity/verify?from=…&to=…).
  2. IntegrityService replays block headers and validates hashes/signatures for that window. Any mutation breaks the chain and is surfaced.
  3. Verification output includes: block range, merkle/hash proofs, signature set, and status.

Data & compliance

  • Results are tamper-evidence artifacts usable in audits and eDiscovery.

Observability

  • Traces link the verification request through Gateway → IntegrityService; verification metrics exposed with OTel.

UC-Z2 — Breach notification pipeline

Actors IntegrityService, Compliance/Security, Tenant Webhook Consumer, API Gateway.

Intent When an integrity violation or unauthorized access is detected, emit a signed SecurityIncident webhook to the tenant endpoint.

Preconditions

  • Webhook channel is registered and signed; tenant endpoint verified.
  • Integrity/monitoring rules configured to raise violations.

Main flow

  1. Integrity/Access monitor flags violation → SecurityIncident event is composed with evidence pointers (block ids, hash).
  2. Gateway delivers a signed webhook to the tenant endpoint with status and remediation references.
  3. Tenant systems acknowledge and begin incident runbook; ATP maintains an immutable incident record.

Data & compliance

  • Incident payload references affected integrity blocks; all messages signed to preserve chain of custody.

Observability

  • Exported incident counters and delivery metrics; dashboards correlate violations to affected tenants.

UC-Z3 — Workload identity & mTLS access to Query API

Actors API Gateway, Backend Services, Identity Provider, Audit.QueryService.

Intent Enforce least privilege with workload identity + mTLS for service-to-service calls to Query APIs; capture attestations as evidence.

Preconditions

  • Gateway configured for OIDC and mTLS; services use SPIFFE/SPIRE identities.
  • Trust boundaries: public (OIDC/TLS 1.3) and control (mTLS + JWT).
  • Optional inline mTLS enforcement at edge (reference impl).

Main flow

  1. Caller obtains client-credentials token and presents mTLS connection to Gateway.
  2. Gateway validates cert + JWT, normalizes identity headers (tenant, roles, scopes), and forwards to QueryService.
  3. QueryService re-validates and authorizes on least-privilege scopes; response includes standard integrity metadata.

Data & compliance

  • All hops authenticated; zero-trust posture ensures internal networks cannot bypass auth or modify evidence.

Observability

  • Continuous attestation (image signatures/config hashes) logged and auditable alongside access traces.

UC-Z4 — “Policy applied” evidence (auditability of the auditor)

Actors Audit.PolicyService, Compliance/Security, Export/Query Services.

Intent Emit signed PolicyApplied events for every retention/redaction cycle to provide auditability of the auditor itself.

Preconditions

  • Policy engine evaluates retention/hold conditions and records outcomes.

Main flow

  1. On each policy execution, PolicyService emits a PolicyApplied event (scope, policy id, counts, timing) and stores it immutably.
  2. Events appear in Query and are bundled with exports as compliance evidence.

Data & compliance

  • Events are signed and linked to affected records; they demonstrate deterministic, policy-as-code governance.

Observability

  • Policy execution metrics and SLOs visible in dashboards; correlates with retention accuracy.

SRE & Operations Flows (SLOs, health, cost, resilience)

Operator-centric scenarios that keep pipelines green, APIs healthy, and evidence verifiable—grounded in ATP’s runbooks, observability stack, and lifecycle.

UC-O1 — DLQ replay & idempotent re-ingest

Actors SRE/Operator, Audit.IngestionService, Audit.StorageService, API Gateway.

Intent Safely drain DLQs and reprocess audit messages without duplication, relying on the platform’s Outbox + Retry + DLQ integration points.

Preconditions

  • SRE confirms service health via /health or HealthCheck UI and reviews Runbook steps.
  • Observability is enabled (OTel exporters, dashboards).

Main flow

  1. Identify failing subscription(s); snapshot DLQ depth and error categories from Grafana.
  2. Start controlled replay (batch/interval). Messages traverse the standard Ingestion → Storage path.
  3. Re-ingest relies on idempotent append semantics from the Outbox pattern; duplicates are coalesced by the pipeline.
  4. Validate recovery by checking ingestion throughput, latency, and error-rate SLOs.

Data & compliance

  • Replayed records remain append-only and re-linked into the tenant’s integrity chain (no rewrites).

Observability

  • End-to-end traces confirm replay success; Operator Checklist step “Observe Metrics” confirms stabilized rates.

UC-O2 — Hot shard & rate-limit protection

Actors API Gateway, SRE/Operator, Producer Services.

Intent Mitigate hot partitions by enforcing Gateway rate limits and documenting backpressure guidelines for producers.

Preconditions

  • Gateway policies for authentication and rate limiting are active; producers follow bus contracts.

Main flow

  1. Detect spikes (ingestion latency, queue length, 429s) on Grafana “Audit Trail / Overview”.
  2. Apply or tighten rate limits on affected routes; communicate current limits to producer teams.
  3. Guide producers to leverage Outbox + Retry rather than synchronous retries; verify DLQ remains stable.
  4. Re-check SLOs and per-tenant isolation signals after throttling.

Data & compliance

  • Throttling never bypasses tenant isolation or security controls enforced at the Gateway.

Observability

  • OTel spans from Gateway → Ingestion highlight queuing time; alerting via Prometheus/Grafana remains in policy.

UC-O3 — Cost-aware export scheduling

Actors SRE/Operator, Audit.ExportService, IntegrityService, Tenant Admin.

Intent Schedule large exports inside SLO windows; ensure results are signed and verifiable upon completion.

Preconditions

  • ExportService configured for async jobs and signed manifests/webhooks.

Main flow

  1. Queue export jobs during off-peak windows to protect ingestion/query SLOs.
  2. On completion, ExportService publishes an artifact with a signed manifest; delivery announced via webhook.
  3. Verify integrity references (hash chain/ledger entries) in the manifest for defensible evidence.

Data & compliance

  • Exports observe residency/retention constraints defined by the tenant’s Compliance Profile.

Observability

  • Dashboards track export durations and sizes; traces cover Gateway → Export pipeline.

UC-O4 — Observability triage

Actors SRE/Operator, All Audit.* services, API Gateway.

Intent Use golden signals and trace stitching to localize faults quickly from Gateway → Export.

Preconditions

  • All services emit OpenTelemetry metrics/traces/logs; Grafana/Jaeger wired via the Operator Checklist.

Main flow

  1. Start at the Operator Checklist: verify health, enable telemetry, observe metrics.
  2. Follow the lifecycle to pinpoint the hop with elevated latency (Gateway → Ingestion → Storage → Query/Export).
  3. Drill into service dashboards (request duration, queue depth, policy timings) and correlate to recent deployments in CI/CD.
  4. Capture a minimal evidence bundle (logs/trace IDs, service version) for incident notes.

Data & compliance

  • Triaged data respects redaction & classification; never expose sensitive fields in logs/dashboards.

Observability

  • The Microservice Template injects tenant/trace IDs, exposes OTel metrics, and standard counters used across ATP.

Conclusion

This document is your practical map for using the Audit Trail Platform (ATP) end-to-end—what to emit, how evidence is protected and verified, how to retrieve/export it, and how to keep the system healthy. It is organized by actors and realistic scenarios, so every team can act with confidence and clear acceptance signals.

What this gives you

  • A consistent, actor-aligned catalog of producer flows and consumer workflows with inputs, required headers, and expected outputs.
  • The platform’s trust guarantees in context: tenant isolation, field-level classification & redaction, append-only storage, rolling hash chains, signed exports, legal holds, and zero-trust access (workload identity + mTLS).
  • Operational playbooks that preserve SLOs under load, enable safe DLQ replays, and provide traceable outcomes across Gateway → Ingestion → Storage → Query/Export.

How to apply it

  • Developers/Integrators: Pick the relevant producer use case, wire the SDK or REST/gRPC edge, include X-Tenant-Id, X-Trace-Id, X-Idempotency-Key, and validate the record in Query.
  • Compliance/Security: Use the timeline/search patterns, apply legal holds where needed, and request signed exports; verify integrity proofs for the audited window.
  • Tenant Admins: Run scoped, self-serve exports through the Gateway with enforced quotas and rate limits; review results with redaction and isolation preserved.
  • SRE/Operators: Monitor golden signals and queues, execute replay procedures safely, throttle hot shards at the edge, and confirm end-to-end health via OTel traces and dashboards.

Ready-to-use checklist (per integration)

  1. Identify the actor + scenario that matches your goal.
  2. Choose the integration edge (SDK, REST/gRPC, bus) and confirm headers & auth scopes.
  3. Map the classification/redaction policy for your payload.
  4. Confirm SLOs/alerts and dashboard coverage; enable DLQ replay runbook.
  5. Run a dry-run: emit → ingest → query/export, and verify integrity proofs.

Where to go next

  • Produce Audit Events (implementation guide)
  • Querying Audit Logs (retrieval patterns & examples)
  • Runbook & Operations (SRE procedures, dashboards, DLQ replay)
  • Architecture & HLD (service responsibilities, lifecycle, interfaces)
  • ADRs & Governance (change management and rationale)

Bottom line: ATP provides provably immutable, isolated, and observable audit evidence for every critical action in the ConnectSoft ecosystem. Use these use cases as your common playbook to implement, operate, and audit with confidence.