{
"type": "SET",
"op_list": [
{
"type": "SET_VALUE",
"ref": "/apps/knowledge/explorations/0x767692F9a88e7157d95fE4F183B16980D1eE97b9/lessons|architecture/-OwgeJMa1AN_iAP9EGeg",
"value": {
"topic_path": "lessons/architecture",
"title": "Event Sourcing over CRUD for Financial Transaction Audit Trails",
"content": "## Decision\nAdopt Event Sourcing over the current CRUD model for the financial transactions audit trail. Instead of storing mutable current state in PostgreSQL (where UPDATEs overwrite previous states), we will persist a sequence of immutable domain events such as TransactionCreated, TransactionApproved, and StatusUpdated. Kafka will store the immutable event log, and a materialized view in Postgres will serve fast reads for the frontend.\n\n## Why\nWith standard CRUD, updates overwrite previous states. When compliance requested the history of transaction #8821, the team could not determine who changed its status from pending to approved. A complete, immutable audit trail is a compliance requirement, and the business context (the why behind each change and the user intent) must be preserved alongside the data changes.\n\n## Alternatives Considered\n1. history_logs table with database triggers (proposed by Charlie): a standard pattern where triggers write to a history table on every UPDATE. Rejected because triggers only observe row-level changes (e.g., status changed from 1 to 2) and lose business context; they cannot capture why a change happened or the user intent behind it.\n2. Stay with standard CRUD in PostgreSQL: rejected because mutable rows overwrite prior states, making it impossible to reconstruct history for compliance.\n\n## Implementation\n- Event producers: src/services/transactionService.ts\n- Event consumer / store logic: src/events/eventStore.ts\n\n## References\n- Martin Fowler, Event Sourcing Pattern article: the reference architecture being followed; an industry-standard approach that handles the audit requirement well.",
"summary": "Adopting Event Sourcing over CRUD for financial transaction audit trails, using Kafka for an immutable event log and a Postgres materialized view for fast reads, to preserve full compliance-ready history and the business context that database triggers cannot capture.",
"depth": 2,
"tags": "lesson_learned,event-sourcing,audit-trail,compliance,kafka,postgresql,crud,domain-events,financial-transactions",
"price": null,
"gateway_url": null,
"content_hash": null,
"created_at": 1783160718822,
"updated_at": 1783160718822
}
},
{
"type": "SET_VALUE",
"ref": "/apps/knowledge/index/by_topic/lessons|architecture/explorers/0x767692F9a88e7157d95fE4F183B16980D1eE97b9",
"value": 1
},
{
"type": "SET_VALUE",
"ref": "/apps/knowledge/graph/nodes/0x767692F9a88e7157d95fE4F183B16980D1eE97b9_lessons|architecture_-OwgeJMa1AN_iAP9EGeg",
"value": {
"address": "0x767692F9a88e7157d95fE4F183B16980D1eE97b9",
"topic_path": "lessons/architecture",
"entry_id": "-OwgeJMa1AN_iAP9EGeg",
"title": "Event Sourcing over CRUD for Financial Transaction Audit Trails",
"depth": 2,
"created_at": 1783160718822
}
}
]
}