part seven · sequence, schema, api

Sequence, Schema, API

The three technical drawings every Epic needs.

Volume III's technical artifact set is small. Three drawings, plus one or more ADRs to constrain them. The drawings are not deliverables — they are the conversation aids that the Tech Lead, the developer, and the QA all read before code begins.

Sequence diagram — what flows where

A sequence diagram shows the flow of a request through the services that handle it. Verbs are arrows. Boxes are services or components. The diagram includes the failure paths, not just the happy path.

The corpus pattern: every Epic has at least one sequence diagram. A single happy-path arrow set with the alt-flow for the most likely failure. A diagram that only shows the happy path is missing the part the on-call will care about.

Schema design — what the system remembers

A schema diagram or written schema definition shows the tables, columns, constraints, and relationships the Epic introduces or changes. The corpus pattern is to write schema in DDL even when the framework would generate it — the canonical form is what the team reviews.

-- Migration: add normalized_display_name to students

ALTER TABLE students
  ADD COLUMN normalized_display_name TEXT
  GENERATED ALWAYS AS (normalize_unicode(display_name)) STORED;

CREATE INDEX idx_students_normalized_name
  ON students (normalized_display_name);

Schema changes are the part of the system most likely to produce migration drama. The corpus pattern: every schema change has a backward-compatible migration plan, written and reviewed before the cycle starts. The plan answers:

• Is the change additive (safe to roll forward) or modifying (requires sequencing)?
• Can the change be reverted in production without data loss?
• What is the read/write pattern during the migration window?
• What is the staging rehearsal plan?

A schema change without a migration plan is a story that has not finished story-writing.

API contract — what the system promises

For every API surface change, an explicit contract: verb, path, request shape, response shape, errors, guarantees.

GET /api/v2/submissions/:id

Path params:
  id            String. Submission ID.

Query params:
  include       Optional, comma-separated. Allowed: "rubric,student".

Response 200:
  {
    id, status, submitted_at,
    student: {
      id, display_name, normalized_display_name
    },
    rubric: { ... }   // present if include=rubric
  }

Response 404:
  { error: "submission_not_found" }

Response 403:
  { error: "not_authorised_for_submission" }

Guarantees:
  - normalized_display_name is always present and non-empty.
  - Read repeatable within a 30s window post-write.

The contract is what the trio agrees on. The implementation conforms to it. Drift between contract and implementation is the most common source of the API broke support tickets.

When state machines are needed

Some entities have multiple states with rules about which transitions are allowed. Submission: pending → in-progress → graded → returned → final. The corpus pattern: when an entity has more than three states, draw the state machine explicitly.

Disallowed transitions are the silent source of bugs. A state diagram that the trio reads at amigos catches them before code.

Data flow — when integration is the point

For Epics that cross system boundaries — third-party integrations, data ingestion, ETL — a data flow diagram shows the full path of the data: source, transformations, persistence, consumers.

The data flow is what surfaces the unhappy paths — what happens to data that fails validation, where it goes, who notices.

When to write which

Drawing	When
Sequence diagram	Always — at least one per Epic
Schema	Whenever a schema change is involved
API contract	Whenever an API surface changes
State machine	When an entity has more than 3 states
Data flow	When an Epic crosses system boundaries

The Tech Lead decides which apply. The decision is named at Epic kickoff.

Part 8 — Ilities Selection →