Skip to content

Study notes

Deep dives on the concepts each phase of the roadmap exercises — written as the phases are built. These complement the ADRs: ADRs record decisions, notes record understanding.

Index

  • Phase 1 — Work Orders service: UUID vs serial keys, pg ENUM vs CHECK, state machines, cross-service references, offset vs cursor pagination, testing strategy
  • Phase 2 — Event-driven architecture: events vs commands, topic routing, at-least-once + idempotency, the dual-write problem, TTL retry + DLQ, testing messaging
  • Phase 3 — Gateway and composition: gateway vs BFF, sync vs async boundaries, timeouts and cascading failure, error pass-through, graceful degradation, cross-service referential integrity
  • Phase 4 — Observability: three pillars, structured logging rules, correlation ids via ALS, RED metrics and the cardinality trap, liveness vs readiness
  • Phase 5 — Kafka: log vs queue, partitions and keys, consumer groups and replay, idempotent projections, push vs pull, keyset pagination in practice
  • Phase 6 — AI triage: LLMs as components (nondeterminism/cost/latency), sync vs async AI, structured outputs, stubbing the model in tests, best-effort semantics, auditable AI decisions
  • Phase 7 — Production hardening: the dual-write fix, SKIP LOCKED relays, idempotency per consumer, probes with consequences, replica counts as documentation
  • Phase 8 — Auth: 401 vs 403, auth placement in microservices, JWT trade-offs, secure-by-default guards, timing-safe compares, identity across sync and async boundaries