Conventions & principles

Core principles repeated across every domain. Learn them once, apply them everywhere.

Core technical principles

1. Identity keys instead of random keys

Each business occurrence has exactly one deterministic key (derived from event identity). Duplicate events, retries, and reconciliation all produce the same key → never create two records for one business occurrence. Every downstream key (NotificationJob, OutgoingMessage, EntityHistory, etc.) is derived from that.

Intentional exception: action-derived flows (recipient/content computed at call-time, no replay identity) intentionally use random GUIDs = at-least-once.

2. Ensure* instead of Create*

Creating an artifact means "ensure it exists": already exists + compatible → always success (idempotent); already exists but content differs → conflict, stop automatic sending, report to support. Do not Upsert Replace sendable artifacts (avoid resending).

Exception: EntityHistory may InsertOrReplace by deterministic key (RowKey is not referenced externally, and overwrite is harmless).

3. Claim before send

Before calling a provider, move OutgoingMessage to Sending with a conditional update. A duplicate that sees the row already Sending/Sent exits → the user does not receive duplicates.

4. Bounded reconciliation instead of outbox

The system does not build a complex outbox. It accepts that a source event may rarely be missed; each provider declares a bounded scan-repair path (watermark, date window, batch) that runs at low frequency to repair.

5. Independent side effects, append-only registry

Each concern (notification, history, etc.) is an independent post-processor walking its own registry. One concern failing must not skip another concern. Adding a new concern = add a new post-processor, not bloating the routing handler or branching inside an existing post-processor.

Invariant tables in the wiki are interpretive summaries to understand behavior, not complete specifications. When in doubt about details → check the system's real behavior.

Back to Foundation overview or explore domains from the home page.