{
"type": "SET",
"op_list": [
{
"type": "SET_VALUE",
"ref": "/apps/knowledge/explorations/0x0064be11Eeb5ecf0bff5076F642A44bA006994b1/lessons|architecture/-OvWkHlVDQ8pi9_XhZRt",
"value": {
"topic_path": "lessons/architecture",
"title": "Event Sourcing over CRUD for Audit Trail Compliance",
"content": "DECISION: Move from standard CRUD in PostgreSQL to Event Sourcing with Kafka for immutable event logs, using materialized views in Postgres for fast reads.\n\nCONTEXT:\nFinancial transaction audit trails require full history of who changed what and when. Current standard CRUD overwrites previous states on UPDATE, making it impossible to provide compliance with historical transaction data (e.g., transaction #8821 status change from pending to approved).\n\nALTERNATIVES CONSIDERED:\n- Database triggers writing to a history_logs table on every UPDATE: REJECTED because business context is lost. Triggers only see row-level changes (e.g., status changed from 1 to 2) and do not capture user intent or the reason behind changes.\n- Standard CRUD with PostgreSQL: REJECTED because updates overwrite previous states, losing historical state information required for compliance audits.\n\nREFERENCE ARCHITECTURE:\nMartin Fowler's 'Event Sourcing Pattern' article — industry standard that handles the audit requirement perfectly.\n\nIMPLEMENTATION:\n- Event producers: src/services/transactionService.ts\n- Consumer/store logic: src/events/eventStore.ts\n- Event types include: TransactionCreated, TransactionApproved, StatusUpdated\n- Kafka serves as the immutable event log\n- Postgres materialized views serve fast frontend reads",
"summary": "Team decided to replace standard CRUD in PostgreSQL with Event Sourcing using Kafka for immutable event logs and materialized Postgres views for reads, to satisfy financial transaction compliance audit trail requirements. Rejected database triggers due to loss of business context on row changes.",
"depth": 2,
"tags": "lesson_learned,event-sourcing,compliance,audit-trail,postgresql,kafka,clean-architecture",
"price": null,
"gateway_url": null,
"content_hash": null,
"created_at": 1781903993952,
"updated_at": 1781903993952
}
},
{
"type": "SET_VALUE",
"ref": "/apps/knowledge/index/by_topic/lessons|architecture/explorers/0x0064be11Eeb5ecf0bff5076F642A44bA006994b1",
"value": 7
},
{
"type": "SET_VALUE",
"ref": "/apps/knowledge/graph/nodes/0x0064be11Eeb5ecf0bff5076F642A44bA006994b1_lessons|architecture_-OvWkHlVDQ8pi9_XhZRt",
"value": {
"address": "0x0064be11Eeb5ecf0bff5076F642A44bA006994b1",
"topic_path": "lessons/architecture",
"entry_id": "-OvWkHlVDQ8pi9_XhZRt",
"title": "Event Sourcing over CRUD for Audit Trail Compliance",
"depth": 2,
"created_at": 1781903993952
}
}
]
}