| name | ai-memory-system-architecture |
| description | System architecture facts: components, data flow, integration boundaries. Load when implementing cross-component features, debugging integration issues, or onboarding to the codebase. Topics: Event sourcing for the billing audit log. |
System Architecture
Auto-generated by ai-memory from AI chat history. Edit memories via ai-memory list / extract / resolve rather than this file — it is fully regenerated on every ai-memory rules --target skills.
Event sourcing for the billing audit log
The billing domain becomes event-sourced. The source of truth is an append-only billing_events Postgres table (InvoiceCreated, LineItemAdjusted, PaymentCaptured, etc.), each row carrying a SHA-256 hash chain over (prev_hash, payload, timestamp). The current invoices table becomes a read-side projection rebuilt from the log. The rest of the app stays on the existing CRUD model — only billing needs this.
Why: Event sourcing answers compliance directly: every state change is a first-class, immutable record. Hash-chaining provides tamper evidence without an external service. Scoping to billing keeps the operational cost contained.
Rejected: Shadow-table journaling rejected — couples write-side logic to bookkeeping and does not give tamper evidence. External audit-log service rejected — added vendor cost without measurable gain over an in-database hash chain.
