# Story 4.10: Pluggable Audit Storage Interface

## Status
Draft

## Story
**As a** compliance-focused platform engineer,
**I want** a pluggable audit storage interface with a simple file backend in core,
**so that** I can route audit trails to enterprise stores (DB/cloud/SIEM) without modifying core.

## Acceptance Criteria
1. Define a `StorageBackend` Protocol with async methods: `write(event: AuditEvent)`, `flush()`, `close()`.
2. Implement `FileStorageBackend` in core that appends JSONL to daily files (existing behavior refactored to use the interface).
3. `AuditTrail` accepts an optional backend instance; defaults to the file backend when not provided.
4. No breaking change to public `audit_*` helpers and `get_audit_trail()`; provide new params for backend injection.
5. Clear extension guidance for extras (e.g., Postgres/ClickHouse, S3/GCS/Azure Blob, Splunk/ELK) with minimal example stubs.
6. Unit tests cover: interface contract, file backend behavior, and `AuditTrail` integration with a mock backend (happy path and failure swallow semantics).

## Tasks / Subtasks
- [ ] Design `StorageBackend` Protocol and minimal error-handling contract
- [ ] Refactor `AuditTrail` to delegate to the backend (`_store_event` → backend)
- [ ] Implement `FileStorageBackend` and wire it as default
- [ ] Add dependency injection path: `AuditTrail(policy, storage_backend=...)`
- [ ] Update docs: architecture/components and epic 4 notes
- [ ] Add unit tests: protocol, file backend, mock backend integration

## Dev Notes
- Relevant Source Tree
  - `src/fapilog/core/audit.py`: `AuditTrail`, JSONL persistence paths
  - `docs/architecture/components.md`, `docs/prd/epic-4-enterprise-compliance-observability.md`
- Patterns & Constraints
  - Async-first; no blocking I/O in core callsites (file writes may remain synchronous via to_thread if needed)
  - Preserve zero global state except existing `get_audit_trail()` singleton for convenience
  - Swallow backend write errors inside audit processing loop (never crash caller)
- Extension Guidance (extras)
  - DB: implement idempotent writes with integrity fields
  - Cloud object stores: buffered writes, periodic flushes
  - SIEM: backpressure/retry policies and circuit breakers

## Testing
- Interface conformance via stub backend (records writes and close calls)
- File backend: writes valid JSONL, rotates by date, survives errors
- AuditTrail: continues processing with backend exceptions; stats reflect enqueued vs. written (optional)

## Change Log
| Date | Version | Description | Author |
| ---- | ------- | ----------- | ------ |
| 2025-08-11 | 0.1 | Draft story created | QA Agent |


