The Playbook - Tech & Architecture (The Spine)
This is the non-negotiable backbone. The structure that prevents chaos from creeping in and decisions from drifting into improvisation. When culture is mature, architecture becomes predictable. When culture is immature, architecture becomes a roulette wheel.
This chapter is the spine we align on so nobody ever asks "Why Service Bus?", "Why DDD?", or "Why envelopes?" again.
The Principles of the Spine - Governance-first architecture has laws
These are the laws you follow if you want systems that do not collapse under panic, pressure, or scale. Everything below - DDD, envelopes, headless-first, service bus - is how these principles materialize in code.
Boundaries Prevent Chaos
Every system fails at the seams. We define the seams explicitly so logic cannot leak sideways.
Decoupling Protects Autonomy
Teams move fast when no one can accidentally break them. Coupling creates fear. Decoupling creates speed.
Observability Is Non-Optional
If you cannot see it, you cannot trust it. Audit trails, diagnostics, and correlation IDs are governance.
Determinism Over Guesswork
Data flows should behave like math, not magic. Deterministic IDs and idempotent messaging eliminate surprises.
Explicit Over Implicit
Hidden logic is future debt with compound interest. We make rules and assumptions visible so they can be tested.
Contract Over Conversation
Systems align because the contracts align. APIs, envelopes, and messages are the single source of truth.
Composability Scales
Entangled systems grow fragile. Modular systems grow strong. We design units that connect cleanly and evolve independently.
These principles are the spine. The patterns below are their physical form.
Domain-Driven Design (DDD) - Each service owns its bounded context
Cosmos Connector owns fetching. Planday Connector owns transforming and ingesting. The Service Bus is the handshake between them. No shortcuts. No "just call the API directly." That is how coupling creeps in. Boundaries protect momentum.
Headless-First - Every service exposes headless APIs/events
No hidden logic. No private backdoors. No side-effects disguised as convenience. Producers produce. Consumers decide what to do.
Envelope Structure - The AuditEnvelope is our governance anchor
The AuditEnvelope carries counts so you know what was fetched, rules so you know why, diagnostics so you know the cost, and correlation IDs so you can trace the whole thing end-to-end. The envelope is not an implementation detail. It is the system.
Counts
So you know exactly what was fetched.
Rules
So you can explain why those items were fetched.
Diagnostics
So you know what it cost (RUs, elapsed ms).
CorrelationId
So you can trace the whole damn thing end-to-end.
Without this, you're blind. With this, you're bulletproof.
Service Bus, Not Shortcuts - No service-to-service calls. Ever.
Cosmos publishes. Planday subscribes. That is the contract. Not a suggestion - a structural law.
Decoupling
Services don't need to know about each other.
Replayability
Messages can be replayed if needed, without affecting the source.
Resilience
When downstream is down, messages queue and process when available.
Idempotency by Design - No one wants double-booked data
We use deterministic MessageIds (Code+FromDate+ToDate). If a message gets re-sent, Service Bus discards it. Messages replay without breaking the source. No duplicates. No surprises. No "we will fix it later" tickets.
No duplicates. No surprises.