Platform — Overview
Platform is the technical "foundation" running behind the scenes: it listens to data changes across the system and automatically triggers consequences — sending notifications, writing history, scheduling reminders — without every feature reimplementing them.
The problem Platform solves
Imagine: when a customer registers, the system must both (1) send a welcome email and (2) write a history row for that account. If every place in code does both itself:
- Duplicated code in dozens of places → easy to get wrong or miss.
- Duplicate sends when an operation is retried → customer receives two identical emails.
- Hard to extend: adding a new notification type means editing many places.
Platform brings these "consequences" into one shared background processor with deduplication.
Three pieces
| Piece | One sentence | Read deeper |
|---|---|---|
| ① Entity Event Flow | When an entity changes, the system publishes an EntityEvent to a queue; worker reads and routes it. | Architecture |
| ② Notification Platform | From event (or direct command), creates NotificationJob and sends it through the delivery pipeline. | Architecture |
| ③ Entity History | From event, writes one EntityHistory row to build the entity audit timeline. | Architecture |
One recurring idea: hybrid + deduplication
The two most important things to remember about Platform:
- Hybrid — There are two ways a notification is created: direct (service creates it) and via event (service only publishes event, worker creates it). Both use the same infrastructure. Why not force one way? See Concepts.
- Deduplicate with deterministic keys — Because queues may deliver an event multiple times, every effect uses a deterministic key so "same event = same row"; retry does not duplicate.
Suggested reading order
- End-user view — Platform is "invisible" to users, but it is why emails arrive at the right time and history timelines are correct.
- Core concepts — EntityEvent, hybrid, idempotency.
- System architecture — components & data flow diagrams.
- Codebase flow — concrete files, workers, classes.
- History & observability — run-history vs entity audit, lookup & observability.
- Data & read/write tables — source entities, Queue/Table/Blob artifacts by flow.
- Common cases — adding a notification, retry handling, over-fire.