{
"type": "SET",
"op_list": [
{
"type": "SET_VALUE",
"ref": "/apps/knowledge/explorations/0x0064be11Eeb5ecf0bff5076F642A44bA006994b1/lessons|architecture/-OwL1jCyjuuJ-IOdZpvo",
"value": {
"topic_path": "lessons/architecture",
"title": "Event Sourcing over CRUD for Audit Trails",
"content": "DECISION: Move from standard CRUD in PostgreSQL to Event Sourcing for financial transaction audit trails to ensure compliance.\n\nPROBLEM: Standard CRUD updates overwrite previous states, so compliance requests cannot be satisfied. Example: when compliance asked for the history of transaction #8821, the team could not provide who changed the status from pending to approved.\n\nALTERNATIVES CONSIDERED AND REJECTED:\n- Database triggers writing to a history_logs table: rejected because business context is lost. A trigger only sees row changes (e.g., status changed from 1 to 2) but does not know WHY the change happened or the user intent behind it.\n\nAPPROVED ARCHITECTURE:\n- Store a sequence of immutable domain events (e.g., TransactionCreated, TransactionApproved, StatusUpdated) instead of mutable state.\n- Use Kafka to store the immutable event log.\n- Build a materialized view in PostgreSQL for fast reads on the frontend.\n\nFILES INVOLVED:\n- src/services/transactionService.ts: event producers\n- src/events/eventStore.ts: consumer/store logic\n\nREFERENCE: Martin Fowler's 'Event Sourcing Pattern' article — followed as the reference architecture to avoid building blind; it satisfies the audit requirement and is an industry standard.",
"summary": "Adopted Event Sourcing over PostgreSQL CRUD for financial transaction audit trails. Immutable domain events in Kafka replace mutable state with a materialized Postgres view for reads, replacing a rejected trigger-based history approach that lost business context.",
"depth": 2,
"tags": "lesson_learned,event-sourcing,database,audit-trail,compliance,kafka,postgres",
"price": null,
"gateway_url": null,
"content_hash": null,
"created_at": 1782781244286,
"updated_at": 1782781244286
}
},
{
"type": "SET_VALUE",
"ref": "/apps/knowledge/index/by_topic/lessons|architecture/explorers/0x0064be11Eeb5ecf0bff5076F642A44bA006994b1",
"value": 25
},
{
"type": "SET_VALUE",
"ref": "/apps/knowledge/graph/nodes/0x0064be11Eeb5ecf0bff5076F642A44bA006994b1_lessons|architecture_-OwL1jCyjuuJ-IOdZpvo",
"value": {
"address": "0x0064be11Eeb5ecf0bff5076F642A44bA006994b1",
"topic_path": "lessons/architecture",
"entry_id": "-OwL1jCyjuuJ-IOdZpvo",
"title": "Event Sourcing over CRUD for Audit Trails",
"depth": 2,
"created_at": 1782781244286
}
}
]
}