technical shaping — the sequence diagram

The sequence diagram

The first technical artifact is the sequence diagram — a left-to-right trace of what happens when Uri's monthly billing cycle runs. Not how the team plans to build it. How it works today, with the failure included. Drawn from observation of production logs and a real billing cycle, the same way the design flow is drawn from observation of Gal.

  scheduler       billing-svc      cardcom      subscription-db
      │               │                │              │
  1   ├──────────────▶│                │              │
      │  run monthly cycle (1st of month, 23:45)
      │               │                │              │
  2   │               ├───────────────────────────────▶
      │               │  fetch active subscriptions (~3,400 rows)
      │               │                │              │
  3   │               │  loop over subscriptions, single worker
      │               │                │              │
  4   │               ├───────────────▶│              │
      │               │  charge request
      │               │                │              │
  5   │               │◀───────────────┤              │
      │               │  5xx for ~993 charges (rate limit + stale plan refs)
      │               │                │              │
  6   │               │  validation drops these silently — no error, no log, no retry
      │               │                │              │
  7   │               ├───────────────────────────────▶
      │               │  mark cycle complete (false positive)

The diagram does what the brief's journey did for Gal — it makes the failure visible at a specific step, with a specific consequence. Step 6 is the silent drop. Step 7 is the lie the system tells itself. Uri's manual reconciliation is what reconnects the system to reality.

Sequence diagrams are not the only diagram the system might need. When a thing has a lifecycle — a charge attempt that goes from pending to succeeded, failed, or retrying — a state machine answers questions a sequence diagram can't: which transitions are legal, which are forbidden, what triggers each move. The Uri Epic will need both. The sequence diagram shows how the cycle runs once; the state machine shows what each charge can become over time. The volume doesn't draw the state machine here — but the team should know to draw one when the lifecycle matters.

The Cardcom dependency in the diagram is a hint at another concern: this Epic is also an integration. Working with a system that isn't yours has its own discipline — reading the third party's contract carefully, modelling its failure modes, choosing retry strategies, deciding what state to keep on our side vs trust the provider to keep. The chain treatment is the same; the depth of integration practice is its own field.

Next — Schema decisions are meaning-carrying →