Bachata Sensual
Jack & Jill (JnJ) · System Architecture & Workflows
System design, checked against the code · dev stage only · AWS serverless

System Architecture, Workflows & Master Use Cases

System design of the Bachata Sensual Jack & Jill competition app, checked claim by claim against the code. The app runs on one stage, dev, and has never been in production. Every use case carries the status the code supports: built, partly built, backend only, switched off, planned or retired.

⚡ Ingress Architecture: Amazon API Gateway v2 HTTP API · AWS Lambda Python 3.13 (FastAPI ASGI) · Amazon DynamoDB Single-Table
Verified: against commit 8aefdced (main) on 2026-11-10. BUILT means: the code is on main at that commit, which the dev pipeline deploys, and a person can reach it as the row states: from a screen, or as an API-only or operations tool by design. Test coverage per use case is tracked in design/testing/use-case-coverage-table.md, not on this page. This pass read code and configuration; it did not call the dev stage and did not run the full test suite. BUILT never means in production: dev is the only deployed stage. Other labels: PARTLY BUILT, BACKEND ONLY (no screen calls it), SWITCHED OFF, DRY RUN ONLY, PLANNED, RETIRED. A rule we chose and the client has not confirmed is labelled as our default.
Public site design: the WBL design language (tokens, type, grid, motion, the hero system and media rules, the component library, the page blueprints) and its build plan, frontend/wbl-design-language-build-plan.md. Ticket 1112: it changes how the public pages look, not the use cases on this page.
Signed-in app design: the WBL app design language (three voices on one kit, six templates, one commit per screen, the friction ladder, the screens of every actor) and its build plan, frontend/wbl-app-design-language-build-plan.md. Ticket 1112, designed and reviewed on 2026-11-14, not built yet: it changes how the signed-in screens look, not the use cases on this page. Summary in the C1-C4 tab, 'The signed-in app design'.
159
Use Cases Traced
72 built and reachable from a screen, 13 built as an API or tool only, 19 partly built, 16 backend only, 4 switched off or dry run, 33 planned, 2 retired.
4,709
Backend Test Functions
Counted at the verified commit, plus 296 frontend unit test files and 22 browser specs. No coverage percentage is claimed.
dev
Only Deployed Stage
The app has never been in production. There is no production pipeline yet.
Clean
Domain Core
No file under backend/domain imports boto3, FastAPI or pydantic.
1 Table
Cloud Persistence
One DynamoDB table, on-demand, five GSIs, point-in-time recovery on.
Filter Role:
W0

Identity & Festival Onboarding

Account sign-up through Cognito, the request to organize, its approval, and festival creation.

4 Features ▼
UC-ACC-01 Create Account & Self-Sign Up
Person ● BUILT
Anyone creates one account with email and password. The browser talks to Amazon Cognito directly (sign-up, then the emailed confirmation code). The backend first sees the person on GET /me. Roles are never Cognito groups: they are records in our table.
UC-ACC-02 Request To Organize Competition
Person ● BUILT
A signed-in person asks to run a competition (the Run a competition with us form). The request waits for the App Owner or the PSA. Someone who already organizes a festival is told so instead.
UC-OWN-01 Review Organizer Request (Approve / Decline)
App Owner, PSA ● BUILT
The App Owner or the PSA approves or declines a request. Approving creates the festival (an Organization) and makes the applicant its OWNER member.
UC-PSA-01 Create Festival Directly (Super-Admin)
PSA ● BUILT · API ONLY
The PSA creates a festival directly through POST /organizations, without a request. API only: no screen creates a festival this way (the PSA screen only lists festivals).
W1

Competition Planning, Divisions & Staff Roles

One-step event creation, the registration deadline, the round plan, the readiness check list and staff jobs.

7 Features ▼
UC-ORG-01 Create Jack & Jill Event (One-Step Setup)
Organizer ● BUILT
One form creates the event (name, city, day, optional venue and sign-up deadline) and one competition per division chosen. The only divisions are Amateur and Pro.
UC-ORG-02 Configure Division Rules
Organizer ◐ PARTLY BUILT
There is no separate rules form and no entry quota. A level's rules are its round plan with the top N per role (UC-DIR-09, on the Director's page); how a level is scored is one fixed rule, printed read-only on its page (nobody sets it). Who may enter a division is the level lock (UC-CMP-07).
UC-ORG-04 Set Registration Deadline
Organizer ● BUILT
The organizer sets the sign-up deadline, a date, for every level of the event at once (event edit). Sign-up reads as closed once that day has passed. Nothing runs on a timer: the state is computed when it is read.
UC-ORG-06 Edit Event Details & Timelines
Organizer ● BUILT
Update the event's name, day, venue and sign-up deadline on every level of the event in one versioned write.
UC-ORG-07 Add Division / Level To Event
Organizer ● BUILT
Add the division an event does not have yet (Amateur or Pro). A division can exist only once per event.
UC-DIR-01 Review Readiness Checklist
Director ● BUILT
A check list computed on request: which staff jobs are still open, how many judges and head judges are granted, how many dancers are checked in, the scoring setup, and warnings.
UC-ADM-01 Assign Staff Roles & Grants
Organizer ● BUILT
The organizer grants a job on one competition: Competition Director, Registration Desk, Floor Manager, Judge, Head Judge or MC. A judge or director cannot also dance in that competition. Revoking or replacing a staff member exists in the backend only (no screen calls it yet).
W2

Registration, Level-Lock & Desk Check-In

Self-registration with the level lock, pasted roster import, check-in with a bib, corrections and the roster freeze.

7 Features ▼
UC-CMP-01 Self-Register For Competition
Dancer ● BUILT
A signed-in dancer picks an event, the division their level allows (Amateur or Pro) and a role (Leader or Follower), before the deadline. There is no payment in this app.
UC-CMP-07 Check Level Eligibility & Locks
Dancer ● BUILT
The dancer sees their level per role and which division they may enter. The server refuses an entry in a division the dancer's level does not allow. Staff can place a dancer in the other division; placing a Pro dancer into Amateur needs a reason (UC-REG-04).
UC-REG-01 Import Competitor Roster (Pasted Rows)
Registration Desk ● BUILT
Desk staff paste a list of dancers (name, email, role) into the import page, before the roster is frozen. The same email twice in one batch is refused. A separate organizer page imports the export of the registration site (UC-REG-01-E13).
UC-REG-02 Check In Competitor & Assign Physical Bib
Registration Desk ● BUILT
Desk staff check a dancer in and give their entry a bib number, unique in that competition. The server suggests the next number of the role's range (leaders from 101, followers from 201 by default).
UC-REG-03 Correct Roster Issue
Registration Desk ● BUILT
Desk staff correct a name, an email or the role of an entry, and scratch or restore a dancer. Each change is audited.
UC-REG-04 Override Competitor Level
Desk, Organizer ● BUILT
Desk staff or the organizer add a dancer to a division their level does not allow. Placing a Pro dancer into Amateur needs a reason (3 to 300 characters), kept on the entry and in the audit log. Placing an Amateur dancer into Pro needs no reason.
UC-DIR-02 Close Check-In & Freeze Roster
Director ● BUILT
The Director or the Registration Desk closes check-in. The freeze records how many dancers are checked in (at least one is required) and stops imports and new entries; heats are made from the checked-in dancers.
W3

Heat Generation, Floor Calling & Final Show

Heat generation, calling heats to the floor, the round plan and advance, the final's couple draw, and the MC screen.

8 Features ▼
UC-FLR-01 Generate Heats (Balanced Allocation)
Floor Manager, Director ● BUILT
Splits the checked-in dancers of a round into numbered heats that fit the floor capacity per role. A criteria final is always one heat. Each heat is created only if it does not exist yet, and updated only at the version read.
UC-FLR-02 Call Heat To Floor
Floor Manager, Director ● BUILT
Marks one heat as on the floor (one heat at a time). Screens that poll, such as the judge page and the public live page, then show it. No message is pushed to anyone. The first call of a round is refused while no judge of the round holds the job, a dancer who is checked in is on no heat, the couples of a final are not drawn, a finalist is in no couple, or a couple of the draw has a scratched dancer. The message tells the floor manager whom to ask and what for.
UC-FLR-03 Advance Or Pause Round Flow
Floor Manager, Director ● BUILT
The Floor Manager or the Director completes, pauses or resumes the heat on the floor.
UC-DIR-03 Override Heat Assignment
Director ● BUILT
The Director moves a dancer to another heat of the round. The move is audited.
UC-DIR-09 Plan Multi-Round Progression (Prelims -> Finals)
Director ● BUILT
The organizer or the Director sets the round plan (Preliminar, Semifinal, Final) and the top N per role that move on. Every level always has a plan (the default is Preliminar, top 6 per role, then Final): a level cannot run without one.
UC-DIR-10 Advance Top N To Next Round (Audited Cut)
Director ● BUILT
Moves the top N per role of a locked round into the next round and makes its heats, in one transaction. The cut is stored as an AdvancementDecision record and audited. It is refused while a tie on the cut line is open.
UC-DIR-11 Draw Final Couples ("Sortear Parejas")
Director ● BUILT
A seeded draw pairs the finalists into couples and sets the running order. The same finalists and the same seed always give the same couples. With unequal numbers a dancer of the smaller role dances twice. The draw is the Director's. The couples are drawn before the final heat is called: the call is refused without a draw.
UC-MC-01 MC Live Stage Presentation Screen
MC ● BUILT
A read-only screen for the MC: the couple on the floor, who is next, the couples of the final and, once published, the results to announce. While a first-place tie waits for the head judge it shows a name-free results pending line.
W4

Judging & Online Scorecard Ingestion (REST)

One submit route for every card (POST /scorecards/{id}/submit) with a client-minted submission_id, the judge's per-card offline outbox, progress and reopen, the head judge's review and tie decisions.

9 Features ▼
W4 NEXT Decided, not built: one scoring path and one result rule
○ PLANNED
UC-JDG-01 View Assigned Heat & Scoring Sheet
Judge ● BUILT
A judge reads their own scorecards on a phone or tablet: the card, the round's scoring snapshot (choices, or scale, criteria and rule) and, for a criteria final, the couples of the current draw. A card belongs to one judge: that judge reads it, and so can the Director, the organizer and the PSA of that competition (never someone who dances in the level). Reading changes nothing on the server.
UC-DIR-04 Monitor Judge Progress & Reopen a Card
Director, Head Judge ● BUILT
A polled progress board (not a push feed): cards sent per judge, each judge's last presence report and the cards still waiting on their phone. The Director or the Head Judge (or the PSA) reopens a sent card with a reason: SUBMITTED becomes REOPENED, the marks stay, and the judge sends again. A reopen is refused once the round's results are claimed by the lock. A sent card of a judge who left the panel (revoked, replaced or erased) is not reopened either, because nobody could send it again; the answer tells the Director the way out (have the judge job given back, or have the judge excluded from the round). Whether the judge still holds the job is decided by an exact rule: the same id, or the account and email of one person.
UC-HJ-01 Review the Private Heat Map Before Publish
Head Judge, Director ● BUILT
The Head Judge and the Director (the organizer read-only) see every judge's marks for a 1-10 or criteria round, with marks far from the panel flagged, plus open ties. HEAD_JUDGE is its own grant: it reviews, reopens cards and decides ties, and it does not score. A head judge scores only when the same person also holds the JUDGE grant. Plain judges and anyone dancing in the level never see this.
UC-JDG-04 Score a Preliminar / Semifinal 1-10 per Dancer
Judge ● BUILT
Rounds with a NUMERIC snapshot (a Preliminar or Semifinal): the judge types 1.0 to 10.0 per dancer (0.1 steps by default), one card per heat, and sees their own live order per role. A sent card can be corrected until the lock claims the round's results.
UC-JDG-03 Score the Final: One Card, Every Couple, Every Criterion
Judge ● BUILT
A planned Final gets a CRITERIA snapshot. The judge scores every drawn couple 1 to 10 on every criterion (five criteria, 0.5 steps by default) and sends ONE complete card for the whole final. The judge's order is derived from the criterion marks (every criterion weighs the same) and must be strict (no two couples with the same total). There is no manual rank override: to change the order the judge changes a mark.
UC-JDG-05 Keep Scoring Offline: Per-Card Outbox & Resend
Judge ● BUILT
Each 1-10 or criteria card the judge sends is queued on the phone (localStorage, one item per card) and sent to POST /scorecards/{id}/submit with the same submission_id until the server answers. A replay of a submission the server already applied is acknowledged without changing marks. Delivery is not guaranteed: a lock, a marks conflict, a revoked grant or a validation error rejects the queued card, and the marks stay on the phone until the judge acts.
UC-HJ-02 Decide a Tie
Head Judge, Director ● BUILT
After lock, a tie that matters (at the cut line or on a final place) goes to the head judge, who orders the tied dancers or couples with a reason. The Director decides when no head judge is granted, or with a reason once the case has been open 15 minutes; the PSA can decide at once. Each decision is a new immutable record and no score ever changes.
W4 MAP Criteria Final: Use Case to Operation to State (verified against the code)
Use case: stepOperationState changeRefused, or recovered, when
UC-ORG-01, UC-DIR-09, UC-DIR-10: the round's scoring snapshot Nobody configures scoring. A round's snapshot comes from Competition.snapshot_for through ScoringMethodSnapshot.for_unit (constants, naming PANEL_AVERAGE 1) Nothing is stored per level besides the round plan. A planned Final gets a CRITERIA snapshot, any other round a NUMERIC one Round 1's snapshot is rewritten only by a round-plan change while it has no heats. A later round takes its snapshot when "Advance top N" creates it
UC-JDG-01: open GET /judges/{judge}/scorecards (the card and the couples of the current draw); the round carries the snapshot No card transition. The judge page also reports presence every 15 s (PUT /judges/me/sync-status, advisory only). The assigned judge reads their own card; the Director, the organizer and the PSA can read it too. A reader who dances in the level is refused. A head judge reads other judges' marks through the review, not through this route.
UC-JDG-03: enter scores On the phone only: a draft in localStorage; the order is computed from the served rule (weighted criterion marks) The local draft changes. Nothing changes on the server. Send stays disabled until every couple has every criterion, the order is strict, the draw is current and the heat was called.
UC-JDG-03: submit or correct POST /scorecards/{id}/submit (kind: CRITERIA), ScoringService.submit_scorecard, Scorecard.submit_couple_scores OPEN, REOPENED or SUBMITTED becomes SUBMITTED. marks_version + 1 only when the marks (or the draw) changed; the same marks again only refresh the submission data. 403 without the assigned judge's own JUDGE grant (HEAD_JUDGE, organizer and PSA do not score). SCORECARD_INCOMPLETE, SCORE_OUT_OF_RANGE, SCORE_STEP_INVALID, JUDGE_ORDER_NOT_STRICT, FINAL_NOT_DRAWN, FINAL_DRAW_CHANGED, HEAT_NOT_STARTED, SCORING_STALE_VERSION, SCORECARD_MARKS_CHANGED (another device changed the marks). SCORECARD_LOCKED once the lock has claimed the results.
UC-JDG-05: queue and retry frontend/src/services/judgeOutbox.ts: enqueue, flush, resend with the same submission_id Local item PENDING, then SENDING (a 30 second lease), then removed on 200. Back to PENDING on a network error, a 5xx, a 401, a concurrent-write answer or a dead lease. REJECTED on a lock, a marks conflict, a 403 or any other 4xx (a conflict with this phone's own earlier send is rebased and resent without asking). A replay of a submission already applied answers 200 with Idempotent-Replay: true and writes nothing, even on a LOCKED card. Delivery is not guaranteed: a REJECTED card keeps its marks on the phone until the judge discards it or, after a conflict, sends this phone's marks again.
UC-DIR-04: reopen POST /scorecards/{id}/reopen, ScoringService.reopen_scorecard, Scorecard.reopen SUBMITTED becomes REOPENED. The marks are kept, marks_version does not move, a new reopen_id is set, audit SCORECARD_REOPENED. Director, Head Judge or PSA, with a reason. 409 ROUND_ALREADY_LOCKED once the lock has claimed the results.
UC-DIR-05: lock POST /competitions/{c}/rounds/{r}/lock, ScoringService.lock_round: calculate, create ROUND#{r} / RESULTS only if absent (the claim), lock each card, lock the round, audit RESULTS created, then each counted card SUBMITTED to LOCKED, then the round to LOCKED. These are separate writes, in this order. The claim is the cutoff for new edits and reopens. If the writes after it stop, the round stays claimed but not LOCKED for as long as nobody acts; tapping lock again, or publishing, finishes it. One exception: a reopen that committed between the lock's read and its claim makes the lock undo its own claim (audit ROUND_LOCK_RELEASED) and answer SCORING_INCOMPLETE.
UC-HJ-02: decide ties POST .../rounds/{r}/ties/{case}/decision, TieBreakService.decide Appends a TieBreakDecision (the next sequence; a correction names the decision it replaces). RESULTS and the scorecards do not change. The round must be LOCKED. Head judge; Director without a head judge, or with a reason after 15 minutes; PSA. 409 after publish.
UC-DIR-06: publish POST /competitions/{c}/rounds/{r}/publish, ResultsPublishingService.publish_results RESULTS marked published (version-checked), then the public snapshot with the placements as resolved by the decisions, then the round (and, for the last round, the competition) to PUBLISHED, then league points. 409 TIES_UNRESOLVED while a tie that matters is open, RESULTS_INTEGRITY_MISMATCH when a card moved since the calculation, ROUND_EMBARGOED. A retry finishes a publish that stopped part way.
W5

Results Calculation, Publishing & Final Show

Locking a round, publishing its results, and the dancer's and the public's views of heats and results.

5 Features ▼
UC-DIR-05 Lock Round & Calculate Results
Director ● BUILT
The Director locks the round. The server calculates by the round's snapshot (the average of the judges' scores, PANEL_AVERAGE 1, recorded on the result with its version), stores the result set as the claim, then locks each card and the round. The claim is the cutoff for edits and reopens; if the later writes stop, lock again or publish finishes them. The lock also refuses while a counted scorecard leaves out an active dancer of its heat, a counted judge has no scorecard for a heat, or a restored dancer is on no heat. A result never silently omits a dancer, and every refusal says how to fix it. The lock of a final also refuses while a couple that is not withdrawn has a scratched member, naming the dancer and the two ways out (restore the dancer, or withdraw the couple). The last couple left is exempt so a final can always lock; its scratched member keeps the place and the points. The status offers the lock once every judge who counts has sent, also after a judge with an unsent scorecard was excluded. The Director's page and its lock confirmation show, in the server's own words, the roster warnings (a dancer with no heat or no couple, couples not drawn, a scratched dancer in a couple, a scorecard that leaves a dancer out, a judge with no scorecard for a heat) and the notices (the dancers scratched after their heat was called, whom locking leaves out for good; the last couple of a final with a scratched member). Each is shown once and none of them turns a button off: the server refuses what it must. On a phone the button that confirms the lock comes after them, so they are read before the tap.
UC-DIR-06 Publish Results & Award League Points
Director ◐ PARTLY BUILT
Publishes a locked round once every tie that matters is decided: the public snapshot stores the placements as resolved by the tie decisions, and the scores stay as the judges sent them. Publishing the last round awards league points (the points table is our default, not yet confirmed by the client). On a round scored 1-10, and whenever results are saved and hidden for the ceremony, publishing is refused while a tie that decides a place is open: the head judge decides first (409 TIES_UNRESOLVED). Every publish path has the tie gate. On dev today, until the push, the older build still has one publish path without it (a known open defect, dev only).
UC-CMP-02 Dancer: View My Heat
Dancer ● BUILT
On My competitions the dancer sees, for each entry, the round and heat number they are in and that heat's status. It shows no partner, no floor number and no timetable.
UC-CMP-03 Dancer: View Official Placement Result
Dancer ● BUILT
Once a round is published, the dancer sees their own result on My competitions: placement, and the league points awarded. Nothing is shown before publish.
UC-AUD-02 Public: View Published Podiums & Placements
Public ● BUILT
A public page shows the published results of a competition, without sign-in. Only locked and published rounds are returned.
W7

Global League Standings, Rankings & Analytics

League tables, the five rankings, the promotion suggestions inbox and festival stats. The points chart and the promotion thresholds are our defaults, not yet confirmed by the client.

5 Features ▼
UC-PUB-01 View League Leaderboard Table
Public ● BUILT
Public season standings by season, division (Amateur or Pro) and role. Points come from the chart stored on each award (WSDC_2026.1C_CHART5, tiers by field size): the owner's standing choice, not confirmed by the client.
UC-PUB-06 View The Five Rankings
Public ● BUILT
Five public rankings defined in the backend: Leaders, Followers, General, Most finals and Breakout (Revelación). They are computed from the stored league standings when read.
UC-ORG-13 Review Promotion Suggestions Inbox
Organizer, Owner ● BUILT
After league points are awarded, a dancer who reaches 2 finals or 40 points in Amateur gets a suggestion to move up to Pro. The organizer of the triggering festival, or the App Owner, approves or declines it (never their own). The thresholds are our default, not confirmed by the client.
UC-ORG-05 View Festival Competition Statistics
Organizer ● BUILT
A festival's numbers for its organizer, computed from its competitions and read live from the table when the page opens.
UC-PSA-04 Backfill League Championship Points
PSA ● BUILT · API ONLY
The PSA re-runs the league award for published results through POST /league/backfill. API only, no screen. Awards are idempotent, so a re-run never doubles points.
W10

App Owner & Platform Administration

The App Owner's area, platform roles and the competition activity log.

4 Features ▼
UC-OWN-04 Open Administration Area (/app/owner)
App Owner, PSA ● BUILT
The App Owner's hub at /app/owner: organizer requests, festivals and promotion suggestions. It is a frontend page gated by the capabilities that GET /me returns.
UC-PSA-06 Grant Platform Role (APP_OWNER, PSA)
PSA ◑ BACKEND ONLY
The grant service is written and tested, but it has no API route and no screen. Today the PSA and the App Owner come from stage configuration (PSA_ACTOR_IDS, APP_OWNER_ACTOR_IDS) and from grant records that only the dev demo seed writes.
UC-PSA-07 Revoke Platform Role (Mandatory Reason)
PSA ◑ BACKEND ONLY
The revoke service is written and tested (a reason is required), but it has no API route and no screen.
UC-ADM-03 View a Competition's Activity Log
Director, Organizer, PSA ● BUILT
The activity log of one competition (not a global log), for its Director, its organizer and the PSA: staff grants, roster changes, heats, locks, reopens, tie decisions and publishes. Entries are append-only. Names are resolved when the log is read.

Click any diagram header to collapse or expand. Every name in these diagrams exists in the code at the verified commit.

Level 1 · C1 System Context Diagram (Official C4 Model)

Scope: the people, the app in scope, and the external systems it really talks to

C1 System Context▼
┌────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│                           PEOPLE (one account per person; jobs are granted per competition)                            │
│                                                                                                                        │
│ Organizer · Competition Director · Registration Desk · Floor Manager · Judge · Head Judge · MC · Dancer                │
│ App Owner (the client) · PSA (technical super admin)                                                                   │
│ Public, no account: league tables, rankings, dancers, events, published results, live screen                           │
└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
                                                            │
                                                            │ HTTPS, browser on a phone, tablet or desktop
                                                            ▼
┌────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│                                       BACHATA SENSUAL JACK & JILL APP (IN SCOPE)                                       │
│                                                                                                                        │
│ • Festivals and events; one competition per division. The only divisions are Amateur and Pro                           │
│ • Sign-up with the level lock, desk check-in with bib numbers, roster freeze                                           │
│ • Heats, calling heats to the floor, the round plan and Advance top N                                                  │
│ • Judging: 1-10 per dancer and a criteria final, the average; lock, tie decisions, publish                             │
│ • The final's seeded couple draw, the running order, the MC screen and the big screen                                  │
│ • League points, standings, five rankings, promotion suggestions; dancer profiles and the public directory             │
│ • Personal data: erasure requests (API only, no screen)                                                                │
└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
                    │                                         │                                       │
                    │ sign-up, sign-in, ID token (JWT)         │ email outbox: DRY RUN ONLY             │ assistant question
                    ▼                                         ▼                                       ▼
┌──────────────────────────────────────┐  ┌──────────────────────────────────────┐  ┌────────────────────────────────────┐
│       AMAZON COGNITO USER POOL       │  │              AMAZON SES              │  │         GOOGLE GEMINI API          │
│                                      │  │                                      │  │                                    │
│ Email and password accounts,         │  │ No stage can send email: the send    │  │ Testing assistant. Backend route   │
│ self sign-up, emailed                │  │ mode is dry_run on every stage and   │  │ only: no screen opens it.          │
│ confirmation code.                   │  │ no ses:SendEmail grant exists.       │  │ Switched off on every stage.       │
│ No groups: every role is a           │  │ Only a suppression-list delete is    │  │ Being removed (ADR-1110).          │
│ record in our own table.             │  │ granted.                             │  │                                    │
└──────────────────────────────────────┘  └──────────────────────────────────────┘  └────────────────────────────────────┘

 There is no payment provider: the app has no payment code. Sign-ups made on the separate registration site
 reach this app only as an export file that the organizer imports.
📐 C1 Invariant: Defines the macro system boundary. Internal architecture is treated as a black box; only human actors and external cloud service integrations are declared.

Level 2 · C2 Container Diagram (Official C4 Model)

Scope: Deployable runtimes, data storage units, client containers, and communication protocols

C2 Containers▼
[BROWSER]
     │
     │ 1. HTTPS
     ▼
┌────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│                             EDGE: AMAZON CLOUDFRONT DISTRIBUTION  (stack jnj-{stage}-web)                              │
│                                                                                                                        │
│ default        ->  S3 site bucket: the built React app (a CloudFront function routes SPA paths to index.html)          │
│ assets/*       ->  S3 site bucket, long cache                                                                          │
│ /media/*       ->  S3 media bucket: dancer photos and event posters                                                    │
│ /api/public/*  ->  the HTTP API, GET and HEAD only, cached: the public reads                                           │
│ /go/*          ->  the HTTP API: the tracked ticket link redirect                                                      │
└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
     │
     │ 2. The app runs in the browser
     ▼
┌────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│                                                    SINGLE PAGE APP                                                     │
│                                                                                                                        │
│ React 19 · TypeScript · Vite · Tailwind CSS · TanStack Query · React Router                                            │
│ Signs in against Cognito directly and calls the API with the Cognito ID token.                                         │
│ The judge's phone keeps score drafts and the per-card outbox in localStorage.                                          │
└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
     │
     │ 3. HTTPS, Authorization: Bearer <ID token>
     ▼
┌────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│                                AMAZON API GATEWAY v2 HTTP API  (stack jnj-{stage}-api)                                 │
│                                                                                                                        │
│ One route: ANY /{proxy+} to the backend function. CORS preflight is answered here.                                     │
│ No authorizer and no throttling rule are configured here: the backend verifies the token.                              │
└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
     │
     │ 4. Lambda proxy event
     ▼
┌────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│                                  BACKEND: AWS LAMBDA  (function jnj-{stage}-backend)                                   │
│                                                                                                                        │
│ Container image · Python 3.13 · FastAPI on Mangum · x86_64 · 1024 MB · 20 s timeout                                    │
│ Verifies the Cognito ID token against the pool's JWKS (RS256). Jobs come from our table; the PSA and App Owner         │
│ ids come from stage configuration.                                                                                     │
│ EventBridge rules invoke the same function for jobs: warmer (5 min), reconciler sweep (15 min, detect only),           │
│ erasure sweep (daily), dancer directory rebuild (daily; being removed, ADR-1110). The last two have an SQS             │
│ dead-letter queue.                                                                                                     │
└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
     │ 5. boto3                        │ 6. presigned PUT              │ 7. PutObject                │ 8. GetParameter
     ▼                                 ▼                               ▼                             ▼
┌──────────────────────────────┐  ┌────────────────────────────┐  ┌──────────────────────────┐  ┌────────────────────────┐
│       AMAZON DYNAMODB        │  │      S3 MEDIA BUCKET       │  │      S3 OPS BUCKET       │  │     SSM PARAMETERS     │
│                              │  │                            │  │                          │  │                        │
│ Table jnj-{stage}-competition│  │ Dancer photos,             │  │ Erasure ledger,          │  │ Email hash pepper,     │
│ PK + SK, five GSIs           │  │ event posters.             │  │ one object per request.  │  │ token signing keys,    │
│ On-demand, PITR on           │  │ Browser uploads with a     │  │ Versioned, Object Lock.  │  │ email allowlist,       │
│ TTL attribute: ttl           │  │ presigned PUT; unconfirmed │  │                          │  │ assistant key.         │
│ TransactWriteItems and       │  │ uploads expire in 1 day.   │  │                          │  │                        │
│ conditional writes           │  │                            │  │                          │  │                        │
└──────────────────────────────┘  └────────────────────────────┘  └──────────────────────────┘  └────────────────────────┘

 Also deployed: the Amazon Cognito user pool (stack jnj-{stage}-auth) and CloudWatch alarms on an SNS topic
 (stack jnj-{stage}-monitoring). Delivery: GitHub Actions. A push to main runs CI and deploys dev.
 There is no production pipeline yet.
📐 C2 Invariant: Five CDK stacks deploy these boxes: storage, auth, api, web and monitoring. Browser traffic is HTTPS; the backend reaches DynamoDB, S3 and SSM with its IAM role.

Level 3 · C3 Component Diagram (Official C4 Model)

Scope: Internal modular decomposition of the Serverless Application Backend (FastAPI Lambda Container)

C3 Components▼
┌────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│                                     AWS LAMBDA: THE FASTAPI APPLICATION (backend/)                                     │
│                                                                                                                        │
│   ┌────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐   │
│   │                                   MIDDLEWARE AND AUTH (app.py, api/shared/)                                    │   │
│   │ RequestContextMiddleware -> CORSMiddleware -> PublicCacheMiddleware -> IdempotencyMiddleware -> router         │   │
│   │ DomainError is turned into the API error body by domain_error_handler. The ID token is verified in             │   │
│   │ api/shared/auth.py (get_auth_context); the caller's jobs are resolved by AuthorizationService.                 │   │
│   └────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘   │
│                                                          │                                                             │
│                                                          ▼                                                             │
│   ┌────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐   │
│   │                                          API LAYER (FastAPI routers)                                           │   │
│   │ 31 routers under backend/api/<area>/routes.py. Main route groups:                                              │   │
│   │ /me, /me/home, /me/profile, /me/league        /organizations, /organizer-requests, /events                     │   │
│   │ /competitions/{id}/... (roster, staff, heats, rounds, round-plan, final show, lock, publish)                   │   │
│   │ /scorecards/{id}/submit | reopen   /judges/{id}/scorecards, /judges/me/sync-status                             │   │
│   │ /public/... (league, dancers, divisions, competitions, events)   /promotion-suggestions, /erasure-requests     │   │
│   │ /health                                                                                                        │   │
│   └────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘   │
│                                                          │                                                             │
│                                                          ▼                                                             │
│   ┌────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐   │
│   │                                  APPLICATION SERVICES (backend/application/)                                   │   │
│   │ ServiceContainer (startup/container.py) wires the services. The main ones:                                     │   │
│   │ • EventPlanningService, CompetitionPlanningService : events, one competition per division, readiness           │   │
│   │ • RegistrationService                               : sign-up, level lock, roster, check-in, freeze            │   │
│   │ • HeatManagementService                             : make heats, call, pause, complete, move a dancer         │   │
│   │ • ScoringService                                    : submit a card, reopen, lock                              │   │
│   │ • ScoringReviewService, TieBreakService             : the private heat map; tie cases and decisions            │   │
│   │ • RoundProgressionService, FinalShowService         : round plan and advance; couple draw, cue, live views     │   │
│   │ • ResultsPublishingService, LeagueService           : publish; points, standings, rankings                     │   │
│   │ • AccessControlService, AuthorizationService        : staff grants; who may do what                            │   │
│   │ • DancerProfileService, PromotionService, AdministrationService (audit), PersonalDataService (erasure)         │   │
│   └────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘   │
│                                                          │                                                             │
│                                                          ▼                                                             │
│   ┌────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐   │
│   │                                     DOMAIN (backend/domain/, pure Python)                                      │   │
│   │ Records: Competition (with Round, PlannedRound), Competitor, Heat, Scorecard, ResultSet,                       │   │
│   │          PartnerDraw, FinalShow, AdvancementDecision, StaffAssignment, Organization, PointsAward, Standing     │   │
│   │ Values:  ScoringMethodSnapshot, ScoreScale, Criterion, TieCase, TieBreakDecision, BibNumbering, DrawnCouple    │   │
│   │ Rules are functions, not service classes: calculate_v2_results (one rule, PANEL_AVERAGE),                      │   │
│   │          relative_placement, sum_placement, detect_ties, resolve_placements, compute_advancement_cut,          │   │
│   │          draw_partners, staff_admission, build_rankings                                                        │   │
│   │ No file under backend/domain imports boto3, FastAPI or pydantic (checked by a test).                           │   │
│   └────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘   │
│                                                          │ ports: the Repository protocols in domain/repositories.py   │
│                                                          ▼                                                             │
│   ┌────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐   │
│   │                             ADAPTERS (backend/persistence/, backend/integrations/)                             │   │
│   │ • persistence/: DynamoDBTable and the DynamoDB...Repository classes (competition, participant, heat,           │   │
│   │   scorecard, result, staff, league, final show, scoring v2, embargo, erasure, email), DynamoDBIdempotencyStore │   │
│   │ • integrations/: S3MediaStorage, S3ErasureLedger, SesEmailSender and DryRunEmailSender (dry run is the one     │   │
│   │   in use), SsmEmailPepperProvider, SsmSigningKeyProvider, HmacTokenSigner, GeminiClient                        │   │
│   └────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘   │
└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
📐 C3 Invariant: Strict Clean Architecture dependency flow: Routers depend on Application Services; Application Services depend on Domain Core and Persistence Ports. Infrastructure adapters sit at the boundary.

Level 4 · C4 Component & Data Architecture Diagram (Official C4 Model)

Scope: Part 1 - Domain Bounded Contexts & Aggregate Roots | Part 2 - Persistent Model Overview (ERD & Cardinality) | Part 3 - DynamoDB Single-Table Schema

C4 Code & Data▼
PART 1 · BOUNDED CONTEXTS AND THE RECORDS THEY OWN (backend/domain)
─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  Identity (API layer)              Tenancy / Organization                    Access Control
  AuthContext, Caller               Organization, OrganizationMembership,     StaffAssignment, StaffRevocation,
  (the Cognito ID token)            OrganizerRequest                          PlatformGrant
                                              │ a festival owns its competitions        │ authorizes every call on a competition
                                              ▼                                         ▼
                                    Competition Management ◄────────────────────────────┘
                                    Competition (root: rounds, round plan, bib numbering)
                                    + Round Progression (AdvancementDecision) + Final Show (PartnerDraw, FinalShow) + Event Media
                                              │ entries
                                              ▼
  Dancer Profile ── level per role ─► Participant Management
  DancerAccountProfile,               Competitor, CheckInEvent, RosterFreeze; Registration Level Lock (the division a dancer
  PublicDancerCard                    may enter)
                                              │ checked-in dancers
        ▲                                     ▼
        │ an approved promotion        Floor Operations
        │ raises the level             Heat, HeatAssignment
        │                                     │ one scorecard per judge per heat
  League & Stats                              ▼
  PointsAward, Standing, LeagueTable,  Scoring
  PromotionSuggestion, rankings,       Scorecard, ScoringMethodSnapshot, ResultSet; scoring v2: TieCase,
  season close                         TieBreakDecision, JudgeExclusion, CoupleWithdrawal; Judge Review (the private heat map)
        ▲                                     │ a locked result set
        │                                     ▼
        └──── points on publish ────── Publishing
                                       PublishedResultSnapshot; results embargo (backend only, no screen)

  Across all: Administration (AuditEntry, append-only) · Notifications (email outbox, dry run only) · Personal Data (erasure)
─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
PART 2 · STORED RECORDS AND HOW THEY RELATE (every item: PK, SK, entity_type, the record as a JSON payload)
─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  Organization                ORG#{org} / META
    1 ──< OrganizationMembership   ORG#{org} / MEMBER#{person}#{role}
    1 ──< Competition              COMP#{comp} / META                     one per division of an event. An event is the event_id
                                                                          field; EVENT#{event} / LEVEL#{level} is the claim
  Competition
    1 ──< Round                    COMP#{comp} / ROUND#{round}            (+ ROUND#{round} / SCORING_METHOD, the snapshot copy)
    1 ──< Competitor               COMP#{comp} / COMPETITOR#{id}          (+ BIB#{number} and EMAIL#{email} lookup items)
    1 ──< StaffAssignment          COMP#{comp} / STAFF#{person}#{role}
    1 ──< AdvancementDecision      COMP#{comp} / ADVANCE#{from_round}
    1 ──< PublishedResultSnapshot  COMP#{comp} / PUBLISHED#{round}
    1 ──< PointsAward              COMP#{comp} / AWARD#{round}#{competitor}
    1 ──< AuditEntry               COMP#{comp} / AUDIT#{time}#{id}
  Round
    1 ──< Heat                     ROUND#{round} / HEAT#{heat}
    1 ──0..1 ResultSet             ROUND#{round} / RESULTS                (created once by the lock: the claim)
    1 ──< TieBreakDecision         ROUND#{round} / TIEBREAK#{case}#{sequence}
    1 ──0..1 FinalShow             ROUND#{round} / FINAL_SHOW             (+ one PartnerDraw item per draw)
  Heat
    1 ──< HeatAssignment           HEAT#{heat} / ASSIGNMENT#{competitor}
    1 ──< Scorecard                HEAT#{heat} / SCORECARD#{judge}        one per judge (+ SCORECARD#{id} / META, the lookup copy)
  Account
    1 ──0..1 DancerAccountProfile  ACCOUNT#{account} / DANCER_PROFILE     (+ DANCER#{dancer} / PUBLIC_CARD, the public card)
  League
    Standing                       LEAGUE#{season}#{level}#{role} / DANCER#{dancer}
─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
PART 3 · AMAZON DYNAMODB SINGLE TABLE: KEYS AND WRITE RULES (table jnj-{stage}-competition)
─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
┌────────────────────────────┬──────────────────────────────────┬──────────────────────────────────┬─────────────────────────────┐
│ ENTITY                     │ PARTITION KEY (PK)               │ SORT KEY (SK)                    │ WRITE RULE                  │
├────────────────────────────┼──────────────────────────────────┼──────────────────────────────────┼─────────────────────────────┤
│ Organization               │ ORG#{org}                        │ META                             │ put                         │
│ Competition (one division) │ COMP#{comp}                      │ META                             │ versioned put               │
│ Event level claim          │ EVENT#{event}                    │ LEVEL#{level}                    │ create only if absent       │
│ Round                      │ COMP#{comp}                      │ ROUND#{round}                    │ conditional on status read  │
│ Competitor                 │ COMP#{comp}                      │ COMPETITOR#{id}                  │ versioned put, transactions │
│ Bib lookup                 │ COMP#{comp}                      │ BIB#{number}                     │ create only if absent       │
│ Staff assignment           │ COMP#{comp}                      │ STAFF#{person}#{role}            │ create; re-grant at version │
│ Heat                       │ ROUND#{round}                    │ HEAT#{heat}                      │ create if absent; update at │
│                            │                                  │                                  │ the version read            │
│ Scorecard (one per judge)  │ HEAT#{heat}                      │ SCORECARD#{judge}                │ transaction at the version  │
│ Scorecard lookup copy      │ SCORECARD#{id}                   │ META                             │ read; same transaction      │
│ Result set (the lock claim)│ ROUND#{round}                    │ RESULTS                          │ create only if absent       │
│ Tie-break decision         │ ROUND#{round}                    │ TIEBREAK#{case}#{sequence}       │ create only, append         │
│ Final show, partner draw   │ ROUND#{round}                    │ FINAL_SHOW; one item per draw    │ versioned put; create only  │
│ Published result           │ COMP#{comp}                      │ PUBLISHED#{round}                │ create only if absent       │
│ Advance decision           │ COMP#{comp}                      │ ADVANCE#{from_round}             │ create only, in the advance │
│ League award               │ COMP#{comp}                      │ AWARD#{round}#{competitor}       │ create only (idempotent)    │
│ League standing            │ LEAGUE#{season}#{level}#{role}   │ DANCER#{dancer}                  │ versioned put               │
│ Dancer profile             │ ACCOUNT#{account}                │ DANCER_PROFILE                   │ versioned put               │
│ Audit entry                │ COMP#{comp}                      │ AUDIT#{time}#{id}                │ append only                 │
│ Idempotency marker         │ IDEMPOTENCY#{actor}#{key}        │ META                             │ conditional claim, ttl 24 h │
└────────────────────────────┴──────────────────────────────────┴──────────────────────────────────┴─────────────────────────────┘
 Indexes (main uses): GSI1 lists items by entity_type; GSI2 finds a person's staff grants and festival memberships;
 GSI3 finds a dancer's entries by email or account; GSI4 lists a round's heats, scorecards and results;
 GSI5 lists a judge's scorecards.
📐 C4 Invariant: The contexts and record names are the ones in backend/domain. The keys are the ones the repositories in backend/persistence write. No latency figure is claimed.

Architectural Sequence Deep Dive · Idempotent REST Score Ingestion

Scope: one 1-10 or criteria card from the judge's phone to the one transaction that stores it

Sequence Flow▼
[JUDGE PHONE: OUTBOX]                     [API GATEWAY v2 HTTP API]            [LAMBDA: FASTAPI]                       [DYNAMODB]
              │                                         │                                    │                                 │
   Judge taps Send on a 1-10 or criteria card           │                                    │                                 │
   The outbox mints submission_id once (a UUID)         │                                    │                                 │
   and marks the item SENDING (a 30 s lease)            │                                    │                                 │
              │                                         │                                    │                                 │
              │── POST /scorecards/{id}/submit ────────►│── passes through (no authorizer) ─►│                                 │
              │   Authorization: Bearer <ID token>      │                                    │   verify the ID token (JWKS)    │
              │   X-Idempotency-Key: <submission_id>    │                                    │── claim IDEMPOTENCY#{actor}#key►│
              │   Body: { submission_id, kind,          │                                    │   (conditional put, ttl 24 h)   │
              │     base_marks_version,                 │                                    │                                 │
              │     scoring_method_version,             │                                    │   route: the caller is the      │
              │     scores | draw_id + couples }        │                                    │   card's judge and holds JUDGE  │
              │                                         │                                    │   on this competition, else 403 │
              │                                         │                                    │                                 │
              │                                         │                                    │  ScoringService.submit_scorecard│
              │                                         │                                    │   1 same submission_id as the   │
              │                                         │                                    │     last applied: answer 200,   │
              │                                         │                                    │     no write (a replay)         │
              │                                         │                                    │   2 validate against the round  │
              │                                         │                                    │     snapshot: complete, scale,  │
              │                                         │                                    │     step, strict final order    │
              │                                         │                                    │   3 stale base + other marks:   │
              │                                         │                                    │     409 SCORECARD_MARKS_CHANGED │
              │                                         │                                    │                                 │
              │                                         │                                    │── TransactWriteItems ──────────►│
              │                                         │                                    │   Put card: HEAT# / SCORECARD#  │
              │                                         │                                    │   Put copy: SCORECARD# / META   │
              │                                         │                                    │   Check the heat was called     │
              │                                         │                                    │   Check ROUND#{round} / RESULTS │
              │                                         │                                    │     is absent (no lock claim)   │
              │                                         │                                    │◄─ committed ────────────────────┤
              │                                         │                                    │   or 409 SCORECARD_LOCKED,      │
              │                                         │                                    │   or 409 HEAT_NOT_STARTED       │
              │◄── 200, the stored card ────────────────│◄───────────────────────────────────┘                                 │
              │                                         │                                                                      │
   The outbox removes the item; the screen says Sent.   │                                                                      │
   The card can still be corrected until the lock claims the round's results.                                                  │
⚡ Sequence Invariant: A 1-10 or criteria submit carries a submission_id minted once on the phone. A retry of a submit that already landed is answered without a second write. A submit that arrives after the lock's claim is refused, and its marks stay on the phone.

Architectural Sequence Deep Dive · Offline Outbox & Reconnect (one card per request)

Scope: the judge's outbox after the signal returns. It sends one card per request to POST /scorecards/{id}/submit. Delivery is not guaranteed

Outbox Flow▼
[JUDGE PHONE: OUTBOX IN localStorage]     [HTTP API -> LAMBDA]                 [SCORING SERVICE]                       [DYNAMODB]
               │                                         │                                    │                                 │
   No signal during heats 1 to 3                         │                                    │                                 │
   Each Send queues ONE item per card (PENDING)          │                                    │                                 │
   with its own submission_id, kept for that send        │                                    │                                 │
   A newer Send of the same card replaces the item       │                                    │                                 │
   The signal returns: the outbox sends the due          │                                    │                                 │
   items one request at a time. Each request first       │                                    │                                 │
   marks its item SENDING: a lease that says which       │                                    │                                 │
   page holds it and since when, good for 30 s           │                                    │                                 │
               │                                         │                                    │                                 │
               │── POST /scorecards/{card 1}/submit ────►│── submit_scorecard ───────────────►│── transaction ─────────────────►│
               │◄── 200 ─────────────────────────────────│◄───────────────────────────────────│◄─ committed ────────────────────┤
               │   item removed                          │                                    │                                 │
               │                                         │                                    │                                 │
               │── POST /scorecards/{card 2}/submit ────►│── submit_scorecard ───────────────►│── transaction ─────────────────►│
               │◄── 409 SCORECARD_LOCKED ────────────────│◄───────────────────────────────────│◄─ RESULTS exists: the round     │
               │   item REJECTED; the marks stay on      │                                    │   was locked while offline      │
               │   the phone and the judge is told       │                                    │                                 │
               │                                         │                                    │                                 │
               │── POST /scorecards/{card 3}/submit ────►│── submit_scorecard ───────────────►│── transaction ─────────────────►│
               │   (the answer is lost on the way back)  │                                    │◄─ committed ────────────────────┤
               │   after 25 s the phone aborts its own   │                                    │                                 │
               │   request: item back to PENDING         │                                    │                                 │
               │── POST again, the same submission_id ──►│── replayed, no second write ──────►│   stored answer (middleware),   │
               │◄── 200, Idempotent-Replay: true ────────│◄───────────────────────────────────│   or same id: no write          │
               │   item removed                          │                                    │                                 │
               │                                         │                                    │                                 │
               │── POST /scorecards/{card 4}/submit ────►│── submit_scorecard ───────────────►│── transaction ─────────────────►│
   The page is reloaded, or the phone kills the tab,     │                                    │◄─ committed, or never reached   │
   while card 4 is SENDING: a lease nobody renews.       │                                    │                                 │
   The new page waits until that lease is 30 s old       │                                    │                                 │
   (it cannot tell a dead page from another open tab),   │                                    │                                 │
   then puts the item back to PENDING: the same          │                                    │                                 │
   submission_id and the same marks, nothing minted.     │                                    │                                 │
               │── POST again, the same submission_id ──►│── submit_scorecard ───────────────►│   already applied: no write     │
               │◄── 200 (a replay, or the first apply) ──│◄───────────────────────────────────│   never reached: stored now     │
               │   item removed                          │                                    │                                 │
               │                                         │                                    │                                 │
   While the page is online it also reports presence every 15 s (PUT /judges/me/sync-status): the Director sees                 │
   which cards are still waiting on the phone.                                                                                  │
⚡ What is and is not built: The outbox is per card, in localStorage (not IndexedDB), and each card is its own request, so one refused card never blocks another. The backend also has POST /scorecards/batch-submit with the same per-card rules (ADR 0004), but no client calls it. SENDING is a lease, not a place to stay (ticket 1110, on main since ca271156): the phone aborts its own request after 25 seconds, and a lease that is 30 seconds old and held by a page that is gone is dead. In both cases the item goes back to PENDING with the same submission_id, so the server either stores it once or answers the replay. One known limit: after a reload the new page waits out the 30 seconds before it sends again.

Demo and test data on dev

Scope: the shared dev site only (never production): where its data comes from, how to tell the kinds apart, what keeps it safe

Dev Data▼
In one minute. Seed data is invented starter data, so the dev site is not empty when people try it: festivals, events, dancers with results and rankings, and demo accounts to sign in with. None of it is a real person: every name is made up and every email ends in example.com. It is written only to the dev site (or a test copy on a developer's PC), never to production. The program that writes it is the seed; it runs once on an empty dev table and takes about three minutes on a PC copy.
The look of the seed (ticket 1110): one face per seeded dancer chosen by name, exactly one event in progress on the seed day, every current event dated from the seed day in its own time zone. The seed code is on dev; the dev data shows it after the next reseed (the morning of a people test), because a landing never reseeds. The counts in the box below are the same before and after. The three minutes were measured with this seed on a local copy.
 [EMPTY DEV TABLE]               [THE SEED PROGRAM]                        [DEV SITE WITH DEMO DATA]
 after a wipe, with a     ──►    lab/dev_seed.py, run once by    ──►     24 events · 47 competitions
 backup kept                     an engineer, owner approved             47 dancers · 27 published results
                                 (about 3 minutes on a PC copy)          959 entries · 10 demo accounts
                                         │
                                         └── refuses: production, a non-empty table,
                                             code that differs from what is deployed
The three kinds of data on dev
Kind Who creates it How you recognise it What removes it
Seed (the demo baseline) The seed program, run by an engineer Looks real on purpose: invented names, no test label, emails at example.com A wipe of the dev table (then a reseed)
Test scenarios The test map and the automatic browser tests Tagged as test: [Test] in the name, a TEST / PRUEBA chip; walled off by the ticket 1104 rules (never in public pages, league points or real competitions) Removed automatically after 24 hours, or by the next build of the same scenario
What real people enter Testers, with their own sign-ups and registrations Their own names and emails A wipe of the dev table removes it too

Not separated today: seed data and real testers' entries share one table, and a wipe removes both. Reseed before a people test, never after testers have registered.

What keeps it safe: (1) it runs only against the dev site or a local copy and refuses production; (2) it refuses a table that is not empty; (3) it refuses when the code on the PC differs from the code deployed on dev; (4) every wipe first writes a verified backup, and one command restores it. Full rules and commands: design/testing/demo-data.md and docs/PEOPLE-TEST-DATA.md.

The signed-in app design (ticket 1112)

Scope: every screen after sign-in, for the dancer, the staff on the floor and the back office. It changes how the screens look and how they are built, not the use cases on this page.

App Design▼
In one minute. One app, three voices, one kit. Dancer pages continue the public site (night hero, one gold action). Staff screens are calm work screens with one commit each, and turn black (Pista) or white (Luz) on event day. Back-office pages are a light queue and a decision panel. Every screen reads its data as the server serves it: a slot the server does not serve is hidden.
 [DANCER: show profile]            [STAFF ON THE FLOOR: work + Event Day]     [BACK OFFICE: work]
 the public site continuing        a keypad, a run sheet, a desk              calm, light, a queue
 ┌ site header ───────────────┐    ┌ StaffHeader 48 · context · ■ LIVE · ▣ ┐  ┌ site header ──────────────┐
 │ night hero: YOUR NEXT DANCE│    │ NowCard: the ONE answer, glance size  │  │ PageHeading               │
 │ one gold action            │    │ the list (cues, heats, roster, cards) │  │ list 5/12 │ detail 7/12   │
 │ MY SEASON fact strip       │    ╞ CommitBar: receipt + ONE commit ══════╡  │ rows are  │ DecisionPanel │
 └────────────────────────────┘    └───────────────────────────────────────┘  │ doors     │ ONE commit    │
  HubPage · FlowPage                JobPage (single | split) · StagePage       └───────────────────────────┘
                                                                               HubPage · WorkPage ·
                                                                               WorkspacePage · FlowPage

 colour, one meaning each:  red square + word = live   ·  red square + TODAY = the dancer's day
                            red band + action = a rejected score card
                            red fill + verb = a destructive commit, only on a confirm step
                            gold fill (white on Pista) = the one commit  ·  gold digit = a win
                            amber square = warning  ·  ink triangle = blocker  ·  ink tick = done
The screens, by actor
Actor Screens Template What changes
Dancer My WBL, My competitions, register, profile, account, delete my data HubPage, FlowPage A night hero with my next dance and one gold action; a result shows only when the server serves it
Judge (LIVE) Waiting, the 1-10 card, the Final card, sync, help (J0-J5) JobPage single The keys never move; tenths drawn where the screen is tall enough; a Next key; 'was 8.0'; 'Missing: 103 and 208' before Send
Head judge (LIVE) Landing, alerts, heat map, tie decision (H0-H3) JobPage, FlowPage The flag list comes first; a tie is placed by taps, with nobody placed at the start; the same request
Competition director (LIVE) Run sheet, confirm steps, check-in, rounds, advance, judges, final show, publish and reveal (D0-D10) JobPage split One run sheet instead of two page trees; one steps rail; a judges board that shows sent or not sent and never a score
Floor manager (LIVE) The heat on the floor, call, pause, heat done JobPage split, always Event Day Live is red, not gold; Heat done is held for 900ms, the same hold as the director's
Registration desk Search, check in with a bib, correct, scratch, walk-in JobPage split One search box for a name, an email or a bib; the bib to hand over at glance size
MC The couple to call, then the lines to read JobPage, read only No commit; a door to the reveal step only when the server serves REVEAL to the person (a Director or the PSA)
Venue and crowd Big screen, phone live view StagePage The WBL brand slots; no stock photo
Organizer Festival home, event page, sign-ups, staff, create and edit, media, imports, stats (O1-O9) WorkPage, WorkspacePage, FlowPage Rows become links; tables with 48px rows; read-only states lose their dead forms
App Owner, PSA Hub, organizer requests, festivals, platform stats, promotions (S1-S5) HubPage, WorkPage, WorkspacePage One door per row instead of a filled button per row; counts as served, with the time they were read
The friction ladder: the weight of a confirmation follows what the action destroys
Rung Pattern Writes (examples)
0 Tap One tap, a receipt line, the inverse one tap away Resume, call heat, record a decision, the Event Day switch, save my profile
1 Hold Hold the button; release early and nothing is sent Heat done
2 Confirm step Its own page: a title that names the action, the served facts, Cancel first, the commit last Close check-in, make heats, lock scores, advance, create an event, add staff
3 Confirm + reason Rung 2 plus a reason with the served limits (optional where the API says so) Pause a heat, reopen a card, exclude a judge, re-make heats, set a dancer's level, decline a request, decide a promotion
4 Confirm + preview + hold Rung 2 with what the public will see, the consequences, and a hold Publish now, hold for the ceremony, reveal
5 Everything + acknowledgement Served consequences, a reason, a checkbox only when the server asks, a hold Cancel a level (it cannot be undone)
What never changes: the scoring rules (B1-B17 of the app design, section 9.1), the judge's outbox and its submission_id, every storage key, every API and wire shape. The backend owns the domain: 23 rules found in the frontend today move unchanged and leave only when the server serves the field, each with its own backend ticket. The live scoring screens are built last, each alone, with both browser scoring runs on every commit. Sources: design/frontend/wbl-app-design-language.md and design/frontend/wbl-app-design-language-build-plan.md.

Domain-Driven Design (DDD) & Bounded Contexts

The domain code lives in backend/domain, in pure Python: no file there imports boto3, FastAPI or pydantic. The eight groups below cover the core flow. The full list of contexts, including the planned ones, is in design/domain/domain-overview.md. Every class, enum value and file named here exists in the code at the verified commit.

Bounded Context Domain Module Aggregate Root / Entities Value Objects Core Business Invariants
Dancer Profile & Directory backend/domain/dancer_profile.py
backend/domain/registration_level.py
backend/domain/dancer_directory.py
DancerAccountProfile (root, one per account)
RoleLevel
ProfileEvent
PublicDancerCard
Division (AMATEUR, PRO)
CompetitorRole (LEADER, FOLLOWER)
LevelAdmission
• One level per role, Leader and Follower.
• A level is set by an organizer, the App Owner or the PSA, or by an approved promotion. Each change is a stored event.
• A dancer self-registers only in the division their level allows.
• The public directory is read live from profiles. The second read model (directory v2) is being removed (ADR-1110).
Competition Management backend/domain/competition_management.py
backend/domain/round_progression.py
backend/domain/competition_cancellation.py
Competition (root: one division of an event)
Round
PlannedRound
AdvancementDecision
CompetitionStatus (DRAFT, READY_FOR_CHECK_IN, CHECK_IN_OPEN, ROSTER_FROZEN, IN_PROGRESS, COMPLETED, PUBLISHED, CANCELLED)
RoundStatus (DRAFT, READY, IN_PROGRESS, LOCKED, PUBLISHED)
RoundKind (PRELIMINAR, SEMIFINAL, FINAL)
• Two divisions only, Amateur and Pro. A division exists once per event.
• An event is not its own record: it is the event_id shared by its competitions.
• A level is scored one way; nothing about it is configured (the scoring settings were removed in the direct route, wave 3).
• Cancelling a competition is built but switched off on every stage, and no screen calls it.
Participant Management & Desk Check-In backend/domain/participant_management.py
backend/domain/competitor_status.py
backend/domain/registration_level.py
Competitor
CheckInEvent
RosterFreeze
CompetitorStatus (REGISTERED, CHECKED_IN, SCRATCHED, MERGED, DISQUALIFIED)
BibNumbering (leaders from 101, followers from 201 by default)
• A bib number is unique in a competition (a lookup item created only if absent).
• One entry per email per competition.
• Staff may place a dancer outside their level; a downward placement (Pro into Amateur) needs a reason.
• A dancer withdrawing their own entry, and the organizer removing one, are designed. Only their domain rules exist.
Floor Operations & Final Show backend/domain/floor_operations.py
backend/domain/final_show.py
Heat
HeatAssignment
PartnerDraw
FinalShow
HeatStatus (READY, CALLED, COMPLETED, PAUSED)
FloorCapacity
DrawnCouple
• One heat on the floor at a time.
• A criteria final is one heat.
• A heat is created only if absent and updated only at the version read.
• The final's couple draw is seeded and repeatable. A redraw is a new record.
• There is no song or partner rotation model in the code.
Scoring backend/domain/scoring.py
backend/domain/scoring_v2.py
backend/domain/scoring_v2_results.py
backend/domain/scoring_rule.py
backend/domain/judge_review.py
Scorecard
ResultSet
TieBreakDecision
JudgeExclusion
CoupleWithdrawal
ScoringMethodSnapshot (NUMERIC, CRITERIA; names its result rule, PANEL_AVERAGE 1)
ScoreScale, Criterion, TieCase
ScorecardStatus (OPEN, SUBMITTED, REOPENED, LOCKED)
• Only the assigned judge, holding the JUDGE grant, scores a card.
• Every counted card must be SUBMITTED before the lock.
• The lock's result set is created once. It is the cutoff for edits and reopens.
• How the judges' numbers combine (the average, PANEL_AVERAGE 1), the score steps and the five criteria are our defaults, not confirmed by the client.
• Audit records are plain append-only items. Nothing is cryptographically signed.
League Standings & Promotions backend/domain/league.py
backend/domain/promotions.py
backend/domain/rankings.py
backend/domain/season_close.py
PointsAward
Standing
LeagueTable
PromotionSuggestion
PointsSchedule (WSDC_2026.1C_CHART5: tiers by field size; 5 to 10 dancers in a role pay 3, 2, 1)
PromotionThresholds (2 finals or 40 points)
Both are the owner's choice, not confirmed by the client.
• Points are awarded when the last round is published, once per competitor (a repeat changes nothing).
• A promotion is only suggested. A person approves or declines it.
• The points chart and the thresholds are the owner's standing choice, not confirmed by the client.
• Closing a season: the service exists, with no route and no screen.
Access Control & Staff Grants backend/domain/access_control.py
backend/domain/platform_grants.py
StaffAssignment
StaffRevocation
PlatformGrant
StaffRole (ORGANIZER, COMPETITION_DIRECTOR, REGISTRATION_DESK, FLOOR_MANAGER, JUDGE, HEAD_JUDGE, MC, SYSTEM_ADMIN). ORGANIZER and SYSTEM_ADMIN are never granted as a job. • JUDGING_ROLES (JUDGE, HEAD_JUDGE) and the Director cannot dance in the same competition.
• ROSTER_CONFLICT_OF_INTEREST hides unpublished marks from anyone on the roster.
• HEAD_JUDGE and JUDGE are separate grants.
• Platform grant and revoke: service built, no route, no screen.
Organization & Platform Authority backend/domain/organizations.py
backend/domain/organizer_requests.py
Organization (a festival)
OrganizationMembership
OrganizerRequest
OrganizationStatus (ACTIVE, BILLING_PENDING, SUSPENDED)
OrganizationRole (OWNER, ADMIN, BILLING_ADMIN)
• OWNER and ADMIN members are the organizers of every competition of their festival.
• The PSA and the App Owner come from stage configuration and platform grant records, never from Cognito groups.
• The billing values exist in the enums only. There is no billing or payment code.

Core Entity Dictionary & DynamoDB Single-Table Schema

The main records and the keys the repositories in backend/persistence write. Every item stores the record as one JSON payload attribute next to PK, SK, entity_type and updated_at; the pills are fields of that payload. This is not the whole table: the full key list is in design/persistence/persistence-overview.md.

Domain Entity Partition Key (PK) Sort Key (SK) GSI1 (GSI1PK / GSI1SK) Other Indexes Fields / Attributes (Non-Key) Concurrency Control
Organization ORG#{organization_id} META {entity_type} / {updated_at} -
name country city timezone status created_by organizer_request_id version
Plain put
Event level claim EVENT#{event_id} LEVEL#{level} {entity_type} / {updated_at} -
level competition_id claimed_at request_id
Create only if absent
Competition COMP#{competition_id} META {entity_type} / {updated_at} -
name level event_id event_name event_date city venue status rounds round_plan registration_deadline bib_numbering version
Optimistic (version)
Competitor COMP#{competition_id} COMPETITOR#{competitor_id} {entity_type} / {updated_at} GSI3: {email} or ACCOUNT#{account_id}
first_name last_name email role bib_number status account_id dancer_level level_status level_override_reason checked_in_at scratch_reason version
Version + TransactWriteItems
StaffAssignment COMP#{competition_id} STAFF#{person}#{role} {entity_type} / {updated_at} GSI2: the person's key
staff_user_id role display_name assigned_by assigned_at replaces_assignment_id version
Create, then version
Round COMP#{competition_id} ROUND#{round_id} {entity_type} / {updated_at} GSI4: ROUND#{round_id}
name sequence status scoring_method (the snapshot) entrant_competitor_ids advanced_from_round_id locked_at published_at version
Conditional on the status read
Heat ROUND#{round_id} HEAT#{heat_id} {entity_type} / {updated_at} GSI4: ROUND#{round_id} / HEAT#{status}#{number}
heat_number status assignments called_at completed_at paused_at pause_reason version
Optimistic (version)
Scorecard HEAT#{heat_id} SCORECARD#{judge_user_id} {entity_type} / {updated_at} GSI4: ROUND#{round_id}; GSI5: JUDGE#{judge_user_id}
scorecard_id status numeric_scores couple_scores draw_id marks_version last_submission_id submitted_at reopen_reason locked_at version
Version + TransactWriteItems
Idempotency marker IDEMPOTENCY#{actor_id}#{key} META {entity_type} / {updated_at} -
status fingerprint created_at ttl (24 hours)
Atomic Conditional Put
ResultSet ROUND#{round_id} RESULTS {entity_type} / {updated_at} GSI4: ROUND#{round_id} / RESULTS#LOCKED
leader_results follower_results couple_results tie_cases aggregation judge_count source_card_versions excluded_judges locked_at locked_by published_at version
Created once by the lock; versioned after
DancerAccountProfile ACCOUNT#{account_id} DANCER_PROFILE {entity_type} / {updated_at} -
display_name country city academy instagram photo photo_consent levels (per role) linked_dancer_ids preferred_language version
Optimistic (version)
Standing LEAGUE#{season}#{level}#{role} DANCER#{dancer_id} {entity_type} / {updated_at} -
dancer_name points events finals paid_finals wins podiums best_finish last_event_date recent history version
Optimistic (version)

End-to-End Service Traceability Matrix

One row per use case of the design matrix (design/use-case-service-domain.md): its service, its domain and what it depends on. Each badge is the status the code supports at the verified commit, not the status written in the design. Where the two differ, or where a part is missing, the line Verified says what is true.

UC-ACC-01 ● BUILT
Service: none (frontend calls Cognito directly; first backend read is `GET /me` via AuthorizationSe...
Domain Context: Identity
Dependencies: Cognito (signUp/confirmRegistration)
UC-ACC-02 ● BUILT
Service: OrganizerRequestService
Domain Context: Tenancy / Organization, Identity
Dependencies: OrganizerRequestRepository, OrganizationRepository (already-organizer check)
UC-ACC-03 ● BUILT
Service: JobBoardService (`application/job_board.py`, called by the `/me` route after Authorization...
Domain Context: Access Control, Competition Management, Floor Operations, Participant Management
Dependencies: CompetitionRepository (already loaded by `/me`), HeatRepository via HeatManagementService (any day, a heat on ...
Verified 2026-11-10: The Home and navigation screens that use the job board are in the frontend today.
UC-ACC-04 ● BUILT
Service: HomeService (`application/home.py`: AuthorizationService.list_event_access, JobBoardServic...
Domain Context: Access Control, Participant Management, Competition Management (`job_phase(competition) ==...
Dependencies: none new (the same reads)
Verified 2026-11-10: The Home screen that uses this read is in the frontend today.
UC-PSA-01 ● BUILT · API OR TOOL ONLY
Service: OrganizationOnboardingService
Domain Context: Tenancy / Organization, Identity
Dependencies: OrganizationRepository
Verified 2026-11-10: No screen creates a festival this way. The PSA screen only lists festivals.
UC-OWN-01 (was UC-PSA-02) ● BUILT
Service: OrganizerRequestService (-> OrganizationOnboardingService)
Domain Context: Tenancy / Organization, Access Control (`PlatformAuthority`)
Dependencies: OrganizerRequestRepository, OrganizationRepository
UC-OWN-02 ● BUILT
Service: OrganizationOnboardingService (`list_festival_overviews`), StatsService (festival stats)
Domain Context: Tenancy / Organization, League & Stats
Dependencies: OrganizationRepository, CompetitionRepository, CompetitionActivityReader
UC-ORG-01 ● BUILT
Service: EventPlanningService (-> OrganizationOnboardingService, CompetitionPlanningService per lev...
Domain Context: Competition Management, Tenancy / Organization
Dependencies: CompetitionRepository, OrganizationRepository, OrganizerRequestRepository
UC-ORG-02 ◐ PARTLY BUILT
Service: CompetitionPlanningService
Domain Context: Competition Management, Scoring, Access Control
Dependencies: CompetitionRepository, StaffAccountRepository
Verified 2026-11-10: There is no rules form. A level's rules are its round plan; how it is scored is one fixed rule (the scoring settings were removed in the direct route, wave 3). CompetitionPlanningService has no edit-rules method.
UC-ORG-03 ○ PLANNED
Service: ResultsPublishingService
Domain Context: Publishing
Dependencies: none yet (exports not built)
Verified 2026-11-10: Later. No export code.
UC-ORG-04 ● BUILT
Service: CompetitionPlanningService
Domain Context: Competition Management
Dependencies: CompetitionRepository
Verified 2026-11-10: The deadline is set for the whole event (PATCH /events/{id}). No screen calls the per-competition route.
UC-ORG-06 ● BUILT
Service: EventPlanningService (`update_event_details`) -> CompetitionPlanningService (`change_event...
Domain Context: Competition Management (`EventDetailsChange`, `Competition.change_event_details`), Adminis...
Dependencies: CompetitionRepository (`save_competitions_if_unchanged`), AuditLogRepository
UC-ORG-07 ● BUILT
Service: EventPlanningService (`create_event` with `event_id`)
Domain Context: Competition Management (`EventPlan`)
Dependencies: CompetitionRepository (`claim_event_level` / `release_event_level`)
UC-ORG-08 ● BUILT
Service: RegistrationService (`list_competitors`, the desk's read; since 1028 fills `current_level`...
Domain Context: Participant Management, Registration Level Lock, Dancer Profile
Dependencies: ParticipantRepository, DancerProfileRepository (`get_profiles` batch), CompetitionRepository (`list_competitions_for_event`)
Verified 2026-11-10: The method that lists an event's competitions is list_competitions_for_event.
UC-STF-01 ● BUILT
Service: OperationsStatusService (`jobs_for_access`: `next_step`, `urgency`, `live`; `rank` across ...
Domain Context: Operations Status (`job_urgency`), Competition Management, Access Control
Dependencies: CompetitionRepository, OrganizationRepository (event zone)
UC-DIR-01 ● BUILT
Service: CompetitionPlanningService
Domain Context: Competition Management, Participant Management
Dependencies: CompetitionRepository, ParticipantRepository
UC-DIR-02 ● BUILT
Service: RegistrationService
Domain Context: Participant Management, Competition Management
Dependencies: ParticipantRepository
UC-DIR-03 ● BUILT
Service: HeatManagementService
Domain Context: Floor Operations, Administration
Dependencies: HeatRepository, AuditLogRepository
UC-DIR-04 ● BUILT
Service: ScoringService
Domain Context: Scoring
Dependencies: ScorecardRepository
Verified 2026-11-11 (roster polish, backend slice BE-3a): R4b rule 22. A sent card of a judge who left the panel is not reopened (nobody could send it again): 403 STAFF_JOB_REVOKED with a sentence for the Director that names the way out, decided by the scoring service itself with the exact identity rule of rule 13, and also for an erased judge (before and after the erasure re-keys the cards). The loose identity heuristic that another judge with a similar address or the same display name could switch off is deleted. Nothing is stored.
UC-DIR-05 ● BUILT
Service: ScoringService
Domain Context: Scoring, Floor Operations
Dependencies: ScorecardRepository, ResultRepository, AuditLogRepository, ParticipantRepository
Verified 2026-11-11: card completeness at lock (design/domain/scoring-v2.md R4b). The lock refuses while a counted card leaves out an active dancer, a counted judge has no card for a heat, or an active entrant is on no heat; a restore that a round can no longer place is refused; excluding a replaced judge hands the missing heats to the replacement.
Verified 2026-11-11: slice R1 of ADR-1110 scoring (design/domain/result-rule.md section 3). The lock, the integrity check before publish, the recompute and the review's provisional places compute through one result rule seam, with the same results as before; each result set records the rule that computed it; a stored result that names a rule the build does not have is refused (RESULT_RULE_UNKNOWN) and nothing is written.
Verified 2026-11-11 (ADR-1111 C2 and C6, backend slice BE-1): R4b rules 12 and 15. A final refuses to lock while a couple that is not withdrawn has a scratched member (restore the dancer or withdraw the couple; the last couple is exempt). The next-step read serves a notice, never a blocker, for dancers scratched after their heat was called, and the lock's blockers from the moment they are true; it follows the cards of the judges who count, so it no longer stalls after an exclusion. A lock that goes ahead records what it left out on its audit entry.
Verified 2026-11-11 (frontend slice FE-1): the Director's page and its lock confirmation draw the served roster blockers and notices, each once, with the server's sentence in the reader's language; the refusals are shown as served.
UC-DIR-06 ◐ PARTLY BUILT
Service: ResultsPublishingService (tie gate before the publish mark on 1-10 rounds and on every publish with embargo, scoring-v2 R6b; every publish path has the gate since the direct route, wave 3; on dev today, until the push, the older build still has one publish path without it)
Domain Context: Publishing, Scoring, League & Stats
Dependencies: ResultRepository, AuditLogRepository, LeagueRepository
Verified 2026-11-10: Publish is built. The tie gate runs on the direct publish of a 1-10 round and on the embargo path. One publish path of the older card-based scoring had no gate (a known open defect on dev, ADR-1111 E3); that path was removed in the direct route, wave 3, so every publish path that remains has the gate. Dev keeps the defect until the push.
UC-DIR-07 ● BUILT
Service: AdministrationService
Domain Context: Administration
Dependencies: AuditLogRepository
UC-DIR-08 ● BUILT
Service: HeatManagementService (`remake_heats`, 096)
Domain Context: Floor Operations, Competition Management, Scoring, Administration
Dependencies: HeatRepository, ScorecardRepository, CompetitionRepository, ParticipantRepository, AuditLogRepository
UC-DIR-09 ● BUILT
Service: RoundProgressionService (`round_plan`, `set_round_plan`, 109)
Domain Context: Competition Management (`PlannedRound`, `Competition.set_round_plan`), Administration
Dependencies: CompetitionRepository (versioned save; since 1068 also `ConditionCheck`s on each round's `RESULTS` as read, so...
UC-DIR-16 ● BUILT
Service: RoundProgressionService (`round_plan` serves `edit` + `after_lock_changes`, `set_round_pla...
Domain Context: Competition Management (`Competition.round_plan_edit_policy`, `RoundPlanEditPolicy`, `set_...
Dependencies: CompetitionRepository (versioned save + 1068 `results_as_read` + the `AUDIT#` put in one transaction), Scoring...
Verified 2026-11-10: Built: the round plan page takes the new N with a reason on a locked, unpublished round.
UC-DIR-10 ● BUILT
Service: RoundProgressionService (`preview_advancement`, `advance`, 109) -> HeatManagementService (...
Domain Context: Round Progression (`compute_advancement_cut`, `decide_advancement`, `AdvancementDecision`)...
Dependencies: CompetitionRepository (`save_advancement`: one conditional transaction), ResultRepository, ParticipantReposito...
UC-DIR-11 ● BUILT
Service: FinalShowService (`draw`, `director_view`, 113)
Domain Context: Final Show (`draw_partners`, `make_draw`, `PartnerDraw`, `FinalShow.with_draw`), Competiti...
Dependencies: FinalShowRepository (`save_draw`: one conditional transaction), CompetitionRepository, ParticipantRepository, ...
Verified 2026-11-10: The draw is on the Director's page only.
UC-DIR-12 ◐ PARTLY BUILT
Service: FinalShowService (`cue`, 113)
Domain Context: Final Show (`FinalShow.cue`, `ensure_at_version`), Administration
Dependencies: FinalShowRepository (`save_show`, versioned), AuditLogRepository
Verified 2026-11-10: The cue control is on the Director's page only. The Floor Manager, an actor of this use case, has no cue control on the floor page.
UC-DIR-13 ◑ BACKEND ONLY
Service: ResultsEmbargoService (`place`: calls `ResultsPublishingService.snapshot_through_gates` fo...
Domain Context: Publishing (`EmbargoState`, `EmbargoEvent`), Scoring, Final Show, Administration (`RESULTS...
Dependencies: ResultsEmbargoRepository (`ROUND#/EMBARGO` + `EMBARGO_EVENT#`), ResultRepository, CompetitionRepository, Scori...
Verified 2026-11-10: The backend is built and wired (placement is manual on dev and any other non-prod stage, off on prod). No screen calls it.
UC-DIR-14 ◑ BACKEND ONLY
Service: ResultsEmbargoService (`reveal`: manual reveal only per D21/Q8; commits `T3` via `ResultsE...
Domain Context: Publishing (`EmbargoState.reveal`), League & Stats, Final Show, Administration (`RESULTS_R...
Dependencies: ResultsEmbargoRepository, ResultRepository, CompetitionRepository, LeagueRepository, AuditLogRepository
Verified 2026-11-10: The backend is built and wired (placement is manual on dev and any other non-prod stage, off on prod). No screen calls it.
UC-DIR-15 ◑ BACKEND ONLY
Service: ResultsEmbargoService (`reschedule`: updates advisory `reveal_at` in `T2a` via `ResultsEmb...
Domain Context: Publishing (`EmbargoState.reschedule`), Administration (`RESULTS_EMBARGO_RESCHEDULED`)
Dependencies: ResultsEmbargoRepository, CompetitionRepository, AuditLogRepository
Verified 2026-11-10: The backend is built and wired (placement is manual on dev and any other non-prod stage, off on prod). No screen calls it.
UC-PSA-12 ◐ PARTLY BUILT
Service: ResultsEmbargoService (`refreeze` on a `STALE` embargo after a PSA `recompute_round`...
Domain Context: Publishing (`EmbargoState.refreeze`), Scoring (tie decision on a stale embargo), League & ...
Dependencies: ResultsEmbargoRepository (`T2b`), ResultRepository, ScoringV2Repository, LeagueRepository, AuditLogRepository
Verified 2026-11-10: Refreeze, and the PSA's tie decision on a stale embargo, are built in the backend with no screen. Retracting published results is not built.
UC-REG-01 ● BUILT
Service: RegistrationService
Domain Context: Participant Management
Dependencies: ParticipantRepository (pasted rows; no file-import adapter)
Verified 2026-11-10: Pasted rows, not a file upload.
UC-REG-02 ● BUILT
Service: RegistrationService
Domain Context: Participant Management
Dependencies: ParticipantRepository
UC-REG-03 ● BUILT
Service: RegistrationService
Domain Context: Participant Management, Administration
Dependencies: ParticipantRepository, AuditLogRepository
Verified 2026-11-10: Scratch, restore and correct are built. There is no merge in the code.
UC-FLR-01 ● BUILT
Service: HeatManagementService
Domain Context: Floor Operations, Participant Management, Scoring
Dependencies: HeatRepository, ParticipantRepository, ScorecardRepository, AuditLogRepository
UC-FLR-02 ● BUILT
Service: HeatManagementService
Domain Context: Floor Operations
Dependencies: HeatRepository, ScorecardRepository, ParticipantRepository, StaffAccountRepository, FinalShowRepository
Verified 2026-11-11 (ADR-1111 C5, backend slice BE-1): R4b rule 14. The first call of a round is refused (HEAT_CALL_BLOCKED) while no judge of the round holds the job, a checked-in dancer is on no heat, a final has no draw, a finalist is in no couple, or a couple of the draw has a scratched dancer; the sentence tells the floor manager whom to ask. Before this guard a final called before its draw could be neither drawn nor scored (reproduced before the guard was built). The first call reads the round's scorecards, the roster, the grants and the draw; a read that fails stops the call.
Verified 2026-11-11 (roster polish, backend slice BE-3b): R4b rules 16 and 20. While the first call would be refused, next-step withholds CALL_HEAT and serves the call step blocked with the reason (the guard's own function decides both); the floor manager's entry carries the sentence that says whom to ask. For an undrawn final the blocked step also serves the draw as its way out (blocked.action, with the button's words) and lists DRAW_FINAL for a caller who may draw; no step kind is added. The lock step is blocked the same way while the lock would refuse for the roster. When a fact cannot be read the step is served open and the route decides. No blocker or notice of next-step carries a person's id. The route is unchanged.
UC-FLR-03 ● BUILT
Service: HeatManagementService
Domain Context: Floor Operations
Dependencies: HeatRepository
UC-JDG-01 ● BUILT
Service: ScoringService
Domain Context: Scoring, Floor Operations
Dependencies: ScorecardRepository, HeatRepository
UC-CMP-01 ● BUILT
Service: RegistrationService (`register_dancer`; the signed-in open list `GET /registrations/open` ...
Domain Context: Participant Management, Competition Management, Identity
Dependencies: ParticipantRepository, CompetitionRepository
UC-CMP-02 ● BUILT
Service: RegistrationService
Domain Context: Floor Operations, Participant Management
Dependencies: HeatRepository, ParticipantRepository
Verified 2026-11-10: The read returns the round, the heat number and its status. The heat lookup runs in the route through HeatManagementService.
UC-CMP-03 ● BUILT
Service: RegistrationService
Domain Context: Publishing, Participant Management
Dependencies: ResultRepository, ParticipantRepository
UC-AUD-01 ● BUILT
Service: ResultsPublishingService
Domain Context: Publishing
Dependencies: ResultRepository
Verified 2026-11-10: The live page is served by FinalShowService.
UC-AUD-02 ● BUILT
Service: ResultsPublishingService
Domain Context: Publishing
Dependencies: ResultRepository
UC-ADM-01 ● BUILT
Service: AccessControlService
Domain Context: Access Control
Dependencies: StaffAccountRepository
UC-ADM-02 ● BUILT
Service: AuthorizationService (event access), AccessControlService (staff list)
Domain Context: Access Control, Competition Management
Dependencies: StaffAccountRepository, CompetitionRepository, OrganizationRepository
UC-ADM-03 ● BUILT
Service: AdministrationService (`list_audit_entries_for`: names by reference through the `PersonNam...
Domain Context: Administration
Dependencies: AuditLogRepository, ParticipantRepository (roster), StaffAccountRepository (grants, revocations)
Verified 2026-11-10: Built, including names resolved at read time (ticket 1076). The matrix still calls that part designed.
UC-ADM-04 ● BUILT
Service: AdministrationService; for v2 rounds ScoringService (`recompute_round`, built 127)
Domain Context: Administration, Scoring
Dependencies: AuditLogRepository, ScoringV2Repository (`RESULTS` versioned put + `RESULTS_RECOVERY#`, one transaction)
Verified 2026-11-10: Built for 1-10 and criteria rounds: the Director's integrity card calls the recompute. The matrix still says Later.
UC-ADM-05 ◑ BACKEND ONLY
Service: AccessControlService (`revoke_staff_job`, `list_staff_revocations`: `POST /competitions/{i...
Domain Context: Access Control (`StaffRevocation`), Scoring (`JudgeExclusion`), Administration
Dependencies: StaffAccountRepository, ScoringV2Repository (`JUDGE_EXCLUDED#`), ScorecardRepository, AuditLogRepository (one ...
Verified 2026-11-10: The revoke and history routes exist. No screen calls them. A revoked judge is left out when cards are read and at lock; no exclusion record is written with the revoke.
Verified 2026-11-11: R4b rule 13 (ADR-1111 C3). Revoking the last judge who can finish a running round is refused (JUDGE_EXCLUSION_LEAVES_NO_JUDGES, nothing written); the way out is to replace the judge (UC-ADM-06). Two revokes at the same moment cannot both remove the judges who count on each other, and a revoke cannot go through after the judge it counts on was excluded. Before the round starts the revoke is allowed; the first heat call checks the panel instead (rule 14, see UC-FLR-02). Still no screen. The erasure of a judge is not changed: a judge replaced and then erased, on a panel of one, still leaves a round with no way out (deferred to the privacy design).
UC-ADM-06 ◑ BACKEND ONLY
Service: AccessControlService (`replace_staff_job`: `POST /competitions/{id}/staff/replace`, revoke...
Domain Context: Access Control, Scoring, Participant Management (judge-cannot-dance), Administration
Dependencies: StaffAccountRepository, ParticipantRepository, ScoringV2Repository, AuditLogRepository
Verified 2026-11-10: The replace route exists. No screen calls it.
UC-ORG-18 ○ PLANNED
Service: none committed (an `OrganizationMembership` change; Later, not designed)
Domain Context: Tenancy / Organization, Access Control
Dependencies: OrganizationRepository
Verified 2026-11-10: Later. Not designed.
UC-E2-01 ◐ PARTLY BUILT
Service: none (infrastructure): MonitoringStack alarm topic + one confirmed subscription (planned)
Domain Context: Administration (Operations)
Dependencies: SNS `AlarmTopic`, CloudWatch alarms (`infrastructure/lib/monitoring-stack.ts`)
Verified 2026-11-10: The alarms and their SNS topic exist. No stage has an email subscription: the alarm address is empty.
UC-E2-02 ◐ PARTLY BUILT
Service: none (infrastructure): MonitoringStack dashboard (planned) + runbook entry per alarm
Domain Context: Administration (Operations), Scoring
Dependencies: CloudWatch dashboard, Logs Insights, `design/ops/monitoring-incident-runbook.md`
Verified 2026-11-10: The incident runbook exists. No CloudWatch dashboard is defined.
UC-E2-03 ● BUILT · API OR TOOL ONLY
Service: Reconciler sweep (ticket 1075, round 2: detect-only; a locked round's open tie that matters, a result set's integrity, ...
Domain Context: Scoring (result-set integrity, `TieCase`), League (`SeasonClose.publishes_in_flight`), Adm...
Dependencies: the scheduled rule (every 15 minutes, built), ScoringV2Repository (read only), SeasonCloseRepository (`ReadOnlySeasonClosePort`, round ...
Verified 2026-11-10: Built as a job: a detect-only sweep every 15 minutes, with a heartbeat alarm. It never fixes anything.
UC-E2-04 ◐ PARTLY BUILT
Service: StatsService over a stats read model (planned; chosen in E2-D7) -> observability event emi...
Domain Context: League & Stats
Dependencies: Stats read model (planned), CompetitionActivityReader (today), MonitoringStack (latency alarm)
Verified 2026-11-10: Stats are read live on every stage. The summary read model is built and unused (being removed, ADR-1110). There is no alarm on the stats read itself; only the general Lambda duration alarm.
UC-PUB-01 ● BUILT
Service: LeagueService (`season_champions` -> domain `season_results`: full-season event winners fr...
Domain Context: League & Stats
Dependencies: LeagueRepository
UC-PUB-02 ● BUILT
Service: LeagueService
Domain Context: League & Stats
Dependencies: LeagueRepository
UC-PUB-03 ● BUILT
Service: LeagueService
Domain Context: League & Stats, Publishing, Scoring, Access Control
Dependencies: ResultRepository, ScorecardRepository, StaffAccountRepository, LeagueRepository
UC-PUB-05 ● BUILT
Service: FinalShowService (`live_view`, PUBLIC, 113; while embargoed in E9: `results: null`, no hin...
Domain Context: Final Show, Publishing, Dancer Profile (public card)
Dependencies: FinalShowRepository, CompetitionRepository, ParticipantRepository, ResultRepository, DancerProfileRepository
UC-MC-01 ● BUILT
Service: FinalShowService (`live_view`, MC, 113; reads embargoed `announcements[]` and `champions[]...
Domain Context: Final Show, Publishing, Dancer Profile, Access Control (`StaffRole.MC`)
Dependencies: FinalShowRepository, CompetitionRepository, ParticipantRepository, ResultRepository, ResultsEmbargoRepository ...
UC-MC-02 ✕ RETIRED
Service: none (retired by owner answer Q1, 2026-11-08: MC stays strictly read-only; reveal is trigg...
Domain Context: Final Show, Access Control (`StaffRole.MC`)
Dependencies: none
Verified 2026-11-10: Retired by the owner (2026-11-08). An MC reveal is refused by the API.
UC-SYS-01 ✕ RETIRED
Service: none (retired by owner answer Q8, 2026-11-08: no EventBridge Scheduler timer; `reveal_at` ...
Domain Context: Publishing
Dependencies: none
Verified 2026-11-10: Retired by the owner (2026-11-08). There is no scheduled reveal.
UC-CMP-04 ● BUILT
Service: LeagueService
Domain Context: League & Stats, Identity
Dependencies: LeagueRepository
UC-ORG-05 ● BUILT
Service: StatsService
Domain Context: League & Stats, Competition Management, Participant Management
Dependencies: CompetitionRepository, OrganizationRepository, CompetitionActivityReader (bulk, ticket 054; falls back to Part...
UC-OWN-03 (was UC-PSA-03) ● BUILT
Service: StatsService (+ EventMediaService `ticket_click_totals`, 114; `competitions_by_status` ord...
Domain Context: League & Stats, Competition Management (Event Media; `CompetitionStatus` lifecycle order a...
Dependencies: same as UC-ORG-05 + LeagueRepository, EventMediaRepository (ticket clicks; unknown when unreachable)
UC-OWN-04 ● BUILT
Service: none (frontend `/app/owner` hub; gated on `GET /me.capabilities` from AuthorizationService...
Domain Context: Access Control (`PlatformCapability`)
Dependencies: config `APP_OWNER_ACTOR_IDS`, `PSA_ACTOR_IDS`; from E3-B3 PlatformGrantRepository through `PlatformGrantServic...
UC-PSA-04 ● BUILT · API OR TOOL ONLY
Service: LeagueService.backfill_points
Domain Context: League & Stats, Publishing, Administration
Dependencies: ResultRepository, LeagueRepository, AuditLogRepository
UC-CMP-05 ● BUILT
Service: DancerProfileService (`update_my_profile`) + EmailOutboxService (`_account_language` readi...
Domain Context: Dancer Profile, Notifications (`resolve_message_language`)
Dependencies: DancerProfileRepository, MediaStorage (deletes on consent withdrawal)
UC-CMP-05 (E12 ext: withdraw drops variants) ○ PLANNED
Service: DancerProfileService (`update_my_profile` with `photo_consent=False` -> `_save` -> `media....
Domain Context: Dancer Profile (image variants)
Dependencies: DancerProfileRepository, MediaStorage (`list_keys`, `delete_many`, `delete`)
Verified 2026-11-10: No code. There are no photo variants.
UC-CMP-06 ● BUILT
Service: DancerProfileService (`request_photo_upload`, `confirm_photo`, `remove_my_photo`)
Domain Context: Dancer Profile
Dependencies: DancerProfileRepository, MediaStorage (S3)
UC-CMP-06 (E12 ext: photo variants) ○ PLANNED
Service: DancerProfileService (`confirm_photo` -> after commit `VariantJobPublisher.publish`; repla...
Domain Context: Dancer Profile (image variants, `VariantSpec`, focal point E12-D10)
Dependencies: DancerProfileRepository (`save_profile` with `#pid` condition + cards), MediaStorage (`read`, `put_public`), I...
Verified 2026-11-10: No code (E12).
UC-ORG-09 ● BUILT
Service: LevelChangeService (`apply(origin = the roster row, source = {kind: DANCER_LEVEL_PUT, comp...
Domain Context: Dancer Profile, Registration Level Lock, Participant Management, Administration
Dependencies: DancerProfileRepository, ParticipantRepository, CompetitionRepository, LeagueRepository (the caller's standing...
UC-ORG-10 ● BUILT
Service: EventMediaService (`set_links`, poster upload/confirm, `get_for_organizer`)
Domain Context: Competition Management (Event Media)
Dependencies: EventMediaRepository, CompetitionRepository, OrganizationRepository (authority), MediaStorage
UC-ORG-10 (E12 ext: poster variants) ○ PLANNED
Service: EventMediaService (`confirm_poster` -> after commit `VariantJobPublisher.publish`; replace...
Domain Context: Competition Management (Event Media, image variants)
Dependencies: EventMediaRepository (`save_media` with `#pid` condition), MediaStorage, ImageResizer, VariantJobPublisher (E1...
Verified 2026-11-10: No code (E12).
UC-E12-02 (operator variant backfill, E12-D2) ○ PLANNED
Service: MediaVariantService (`backfill(dry_run=True)` -> `plan_backfill(kinds, cursor, limit)` / `...
Domain Context: Dancer Profile, Competition Management (Event Media), image variants (`classify_for_backfi...
Dependencies: DancerProfileRepository (`list_profiles_with_photo`), EventMediaRepository (`list_media_with_poster`), MediaSt...
Verified 2026-11-10: No code. Only the runbook document exists.
UC-E12-01 (focal point: dancer own photo, operator override, E12-D10) ○ PLANNED
Service: DancerProfileService (`set_focal_point`, `clear_focal_point` -> `FocalPointResult`; PSA or...
Domain Context: Dancer Profile (`FocalPoint`, `set_focal_manual`, `clear_focal`)
Dependencies: DancerProfileRepository
Verified 2026-11-10: No code (E12).
UC-AUD-03 ● BUILT
Service: EventMediaService (`ticket_redirect`)
Domain Context: Competition Management (Event Media)
Dependencies: EventMediaRepository (counters)
UC-PUB-01 / UC-PUB-02 (107 extension) ● BUILT
Service: DancerProfileService (`public_card(s)`) beside LeagueService
Domain Context: Dancer Profile, League & Stats
Dependencies: DancerProfileRepository (`get_card`, `get_cards` batch)
Rule 2026-11-13 (final look 1111, D1): every dancer the public directory lists has a profile page. A dancer with a public card and no league result yet gets a page built from the card (name, photo, levels, zero totals, an empty record); 404 only when there is no named public card either. design/domain/dancer-directory.md "Every listed dancer has a page".
UC-PUB-04 ◐ PARTLY BUILT
Service: DancerDirectoryService (`directory`) over LeagueService (`directory_standings`) + DancerPr...
Domain Context: Dancer Directory, League & Stats, Dancer Profile
Dependencies: LeagueRepository (`list_tables`, `list_standings_many`, `list_dancer_awards`), DancerProfileRepository (`list_...
Verified 2026-11-10: The public dancers page and GET /public/dancers are built and read profiles live, with filters and paging. The second read model (directory v2) and its switch are used by no read and are being removed (ADR-1110).
UC-PUB-07 ○ PLANNED
Service: None committed (would reuse DancerDirectoryService)
Domain Context: Dancer Directory
Dependencies: None committed
Verified 2026-11-10: Later (owner decision D8).
UC-PSA-10 (reset and reseed the dev table; W6; owner-approved writes) ● BUILT · API OR TOOL ONLY
Service: DevDataResetService (`plan`, `apply`, `restore`; prep PR, in-process CLI, never an HTTP ro...
Domain Context: Every context (data removal), Division
Dependencies: `DevTableSweep` (a Protocol in `domain/repositories.py`: `scan_pages`, `delete_batch`, `put_batch`, `identity(...
Verified 2026-11-10: Built as an operator tool for dev only (lab/dev_reset.py and lab/dev_seed.py over DevDataResetService and DemoSeedService). The matrix still says designed.
UC-REG-01-E13 (import paid entries from jnj-registration; owner answers A4, A10; built ticket 1061) ◐ PARTLY BUILT
Service: RegistrationImportService (E13-D7: `import_run(feed)` over the transport-agnostic feed por...
Domain Context: Participant Management, Registration Level Lock, Division, Administration
Dependencies: ParticipantRepository, DancerProfileRepository (batch levels), CompetitionRepository, the E13-D8 link / `IMPOR...
Verified 2026-11-10: The import run and its organizer page are built. The routes for held entries exist and no screen calls them.
UC-E4-01 ◐ PARTLY BUILT
Service: DancerDirectoryProjector (`rebuild(actor_id, dancer_ids=None, next_token=None, *, audit=Tr...
Domain Context: Dancer Directory, Competition Management (`is_competition_live`), Administration
Dependencies: DirectoryRepository (`read_all`, `put_row`, `put_row_checked`, `delete_row(older_than)`, `put_meta`, cursor `O...
Verified 2026-11-10: The rebuild route, job and daily rule exist. The rule does not mark its run as scheduled, so the rule that skips a rebuild while a competition is live does not apply. Being removed (ADR-1110).
UC-CMP-01 (112 extension) / UC-CMP-07 ● BUILT
Service: RegistrationService (`register_dancer` -> `level_check` + `add_competitor`; `registration_...
Domain Context: Participant Management, Registration Level Lock, Dancer Profile
Dependencies: ParticipantRepository (`claim_event_entry`), CompetitionRepository, DancerProfileRepository (`get_profile`)
UC-REG-04 ● BUILT
Service: RegistrationService (`add_competitor` without a level check and without the division check...
Domain Context: Participant Management, Registration Level Lock, Administration
Dependencies: ParticipantRepository (`list_competitors_for_email`), DancerProfileRepository (`get_cards` batch), AuditLogRepository
Verified 2026-11-10: Built: the desk walk-in sends the reason.
UC-ORG-11 ● BUILT
Service: LevelChangeService (`apply(account_id, role, level, actor_id, actor_kind, authority, reaso...
Domain Context: Dancer Profile, Registration Level Lock, Administration
Dependencies: DancerProfileRepository, ParticipantRepository (`list_competitors_for_account_id`, `list_competitors_for_email...
UC-ORG-11-A (review round 2: the in-place keep of a `LEVEL_CHANGED` entry) ● BUILT
Service: RegistrationService (`level_readmit(competition_id, competitor_id, caller, reason)`: `staf...
Domain Context: Registration Level Lock (`staff_admission`, `direction_of`), Participant Management, Administration
Dependencies: ParticipantRepository (`get_competitor`, `save_competitor_if_unchanged`), DancerProfileRepository (`get_profile`), CompetitionRepository, AuditLogRepository (`COMPETITOR_LEVEL_STATUS_CHANGED {trigger: DESK_READMIT}`)
Verified 2026-11-10: Built: route, service and the roster action. The matrix still says designed.
UC-ORG-11-B (2026-11-06, P4: the lost-race repair) ● BUILT
Service: LevelChangeService (`confirm_entry(origin, caller)`: the one-entry re-judge under the curr...
Domain Context: Registration Level Lock (`rejudge_admission`), Participant Management, Administration
Dependencies: ParticipantRepository (`get_competitor`, `save_competitor_if_unchanged`), DancerProfileRepository (`get_profile`), CompetitionRepository, AuditLogRepository (`COMPETITOR_LEVEL_STATUS_CHANGED {trigger}`)
Verified 2026-11-10: Built: route, service and the roster action. The matrix still says designed.
UC-PSA-11 (2026-11-06, P4: sweep stranded pending entries; W6) ● BUILT · API OR TOOL ONLY
Service: LevelChangeService (`rejudge_pending(caller, cursor) -> RejudgeReport`: `CompetitionReposi...
Domain Context: Registration Level Lock, Participant Management, Administration
Dependencies: CompetitionRepository, ParticipantRepository, DancerProfileRepository (batch), the `OPS / REJUDGE_RUN#` record, IdempotencyStore (middleware)
Verified 2026-11-10: API only (POST /registrations/rejudge-pending). There is no command-line tool.
UC-PSA-13 (1043: run the event simulator; W6) ● BUILT · API OR TOOL ONLY
Service: none in production code except the S0 seam: `domain/common.py` gets `set_providers(clock, ...
Domain Context: Every context, read-only over the API; `domain.common` providers
Dependencies: moto DynamoDB and S3 in `mock_aws` (one process, no AWS); `tests/sim/test_sim_smoke.py` in CI's tooling lane...
Verified 2026-11-10: A command-line tool and its smoke tests (backend/sim).
UC-PSA-14 (1043: use-case coverage check; W6) ● BUILT · API OR TOOL ONLY
Service: none (a unit test module `tests/unit/test_use_case_coverage.py` for existence: `CoverageIn...
Domain Context: none
Dependencies: the design files, `junit.xml` (the `junit` artifact of `deploy-dev.yml`), vitest json, `sim run.json`
Verified 2026-11-10: A CI tool (backend/coverage_check).
UC-PSA-15 (1043: browser checks after a dev deploy; W6) ● BUILT · API OR TOOL ONLY
Service: `DevScenarioService.build` gains an optional `namespace` (`demo` by default, `qa-lane` for...
Domain Context: Test Data Visibility (the lane namespace and the `qa-lane-*` accounts)
Dependencies: Cognito hosted login with the dedicated `qa-lane-*` accounts (never a demo account), the dev URL from the repo...
Verified 2026-11-10: A CI lane (browser-checks.yml) that runs after a dev deploy and nightly. The matrix still says designed.
UC-PSA-16 (1043: the unattended night shift; W6) ◐ PARTLY BUILT
Service: none (three systemd user units: a timer, a token unit that mints a 1 h GitHub App installa...
Domain Context: none (process)
Dependencies: the local simulator run, the `Deploy dev` junit artifact, `nightly.yml` artifacts via `gh` with the App token,...
Verified 2026-11-10: The scripts and service units exist under lab/night-shift. They are not installed on any machine.
UC-PSA-17 (1043: review the morning report; W6) ◐ PARTLY BUILT
Service: none (a markdown file under `~/.local/state/jnj-night-shift/reports/` with `latest.md`, ou...
Domain Context: none
Dependencies: the file system; a desktop `notify-send` (no phone push, owner answer 2026-11-07); the pause file `pause-until...
Verified 2026-11-10: The report writer exists. It depends on the night shift, which is not installed, so no report has been written.
UC-DEV-01 ◌ SWITCHED OFF
Service: Assistant (`assistant.py` `answer_question`, a function, not a service class; `POST /assis...
Domain Context: none (read-only digest of counts and states, P13 narrowing planned)
Dependencies: `LlmClient` port (`integrations/gemini_client.py`), `ASSISTANT_ENABLED` (off on every stage, ADR-1110)
Verified 2026-11-11: The route and the service exist. ASSISTANT_ENABLED is false on every stage (ADR-1110, slice S2), so the route answers 404. No screen opens the chat panel. The code itself leaves in a later slice (ADR-1110, S17).
UC-E6-01 (E6) ◐ PARTLY BUILT
Service: EventPlanningService (`set_disclosure`, `set_registration_close`, E6-D4; versioned `EventD...
Domain Context: Competition Management (Event Disclosure, `RegistrationCloseInstant`, `ZonedInstant`), Adm...
Dependencies: CompetitionRepository (`EVENT#{event_id}` partition, E6-D8), AuditLogRepository
Verified 2026-11-10: Only the older date-only deadline can be edited. The disclosure facts and the close instant have no route.
UC-E6-02 (E6) ○ PLANNED
Service: RegistrationService (`open_feed` facts) / public event read
Domain Context: Competition Management (Event Disclosure)
Dependencies: CompetitionRepository (`BatchGetItem` on `EVENT#`)
Verified 2026-11-10: No code.
UC-JDG-04 ● BUILT
Service: ScoringService (`submit_scorecard`, NUMERIC)
Domain Context: Scoring (`Scorecard.submit_numeric_scores`, `ScoreScale`), Floor Operations (heat called)
Dependencies: ScorecardRepository (`save_submitted_scorecard`: version + heat condition), HeatRepository, CompetitionReposit...
Verified 2026-11-10: On dev today, until the push, only a level the older build has switched to the numbers; after the push every level (the one rule).
UC-JDG-03 ● BUILT
Service: ScoringService (`submit_scorecard`, CRITERIA)
Domain Context: Scoring (`Scorecard.submit_couple_scores`, strict judge order), Final Show (current draw),...
Dependencies: ScorecardRepository, FinalShowRepository (current draw), HeatRepository, CompetitionRepository
Verified 2026-11-10: On dev today, until the push, only a level the older build has switched to the numbers; after the push every level (the one rule). One card for the final; no manual rank.
UC-JDG-05 ● BUILT
Service: ScoringService (`submit_scorecard` with `submission_id` / `base_marks_version`), JudgeSync...
Domain Context: Scoring (`Scorecard.last_submission_id`, `marks_version`)
Dependencies: ScorecardRepository, JudgeSyncRepository (`ROUND#r / JUDGE_SYNC#judge`), IdempotencyStore (middleware)
Verified 2026-11-10: The outbox is per card in localStorage. It does not use batch-submit.
UC-HJ-01 ● BUILT
Service: ScoringReviewService (`review`: heat map, provisional results and ties; `alerts`: open ties that matter and outlier counts...
Domain Context: Judge Review (`build_numeric_heat_map`, `build_criteria_heat_map`, outliers), Scoring (provisional `calculate_v2_results`), A...
Dependencies: ScorecardRepository, ResultRepository, CompetitionRepository, StaffAccountRepository, ParticipantRepository (r...
Verified 2026-11-10: The heat map functions are build_numeric_heat_map and build_criteria_heat_map.
UC-HJ-02 ● BUILT
Service: TieBreakService (`cases`, `decide`; head judge, director fallback / override with reason, ...
Domain Context: Scoring (`TieCase`, `TieBreakDecision`, `resolve_placements`, `resolve_result_set`), Acces...
Dependencies: ScoringV2Repository (`save_tie_decision`: conditional create + ConditionCheck on RESULTS version / ADVANCE abs...
Verified 2026-11-10: Decisions are append-only records. Every publish path has the tie gate (see UC-DIR-06).
UC-CMP-08 ● BUILT
Service: RegistrationService (`/me/registrations` result) + ResultsPublishingService (snapshot)
Domain Context: Publishing (v2 snapshot rows), Scoring
Dependencies: ResultRepository, ParticipantRepository
UC-ORG-13 ● BUILT
Service: PromotionService (`list`, `approve`, `decline`; one step Amateur -> Pro, 1028; the record ...
Domain Context: League & Stats (Promotions: `PromotionPolicy`, `PromotionSuggestion`), Dancer Profile, Reg...
Dependencies: PromotionRepository (`DANCER#d / PROMOTION#...`, GSI1 `PROMOTION_SUGGESTION`), DancerProfileRepository, Partic...
Verified 2026-11-10: The service method that lists suggestions is list_suggestions.
UC-ORG-16 (1028 owner answer A2, built in ticket 1051) ◐ PARTLY BUILT
Service: RegistrationService (`move_registration`: pure `move_refusal` then ONE `save_move` transac...
Domain Context: Participant Management (`Competitor`, `RegistrationExit`, `ExitKind.ORGANIZER_MOVED`), Reg...
Dependencies: ParticipantRepository (`save_move`: the exit record, both entries and the claim in one transaction)
Verified 2026-11-10: Moving a dancer to the other division is built on screen. The email about the move is not built.
UC-ORG-19 (ticket 1079) ◌ SWITCHED OFF
Service: CompetitionCancellationService (`cancel`, `exit_entries`, `resume_pending`, `cancel_allowe...
Domain Context: Competition Management (`Competition.cancel`, `cancellation_decision`, `CompetitionCancell...
Dependencies: CompetitionCancellationRepository (one transaction: META, `CANCELLATION`, `AUDIT#`, `ROUND#` and `PUBLISHED#` ...
Verified 2026-11-10: Service and routes are built. COMPETITION_CANCEL_ENABLED is false on every stage, and no screen calls the routes.
UC-ORG-17 (1028 owner answer A9; designed in ticket 1083, v2 of 1053) ◑ BACKEND ONLY
Service: LevelReviewService (`entries(caller, organization_id)`: per in-window competition of the c...
Domain Context: Dancer Profile (`LevelReviewRequest`, `review_target`, `review_availability`, `request_ref...
Dependencies: LevelReviewRepository (`LEVELREVIEW#{id} / REQUEST`, GSI1 `LEVEL_REVIEW_REQUEST`; `ACCOUNT#{a} / LEVELREVIEW_O...
Verified 2026-11-10: Routes and service are built. The frontend has no level review page.
UC-OWN-09 (1028 owner answer A9; designed in ticket 1083, v2 of 1053) ◑ BACKEND ONLY
Service: LevelReviewService (`apply(request_id, reason, caller)`: decider rules first (`OWNER_CONFL...
Domain Context: Dancer Profile (`LevelReviewRequest` transitions, `apply_refusal`, `decline_refusal`), Reg...
Dependencies: LevelReviewRepository, DancerProfileRepository, ParticipantRepository, CompetitionRepository, AuditLogReposito...
Verified 2026-11-10: Routes and service are built. The frontend has no level review page.
UC-OWN-10 (1028 round 4, ticket 1062) ● BUILT
Service: LevelOverridesService (`list_level_overrides(since, limit)` (the route checks `direction=D...
Domain Context: Registration Level Lock (`downward_override_of` / `downward_override_of_entry`: which `COM...
Dependencies: AuditLogRepository (through AdministrationService.list_audit_entries, which names the actor), CompetitionRepos...
UC-PSA-05 ● BUILT · API OR TOOL ONLY
Service: PromotionService (`reconcile`)
Domain Context: League & Stats (Promotions)
Dependencies: LeagueRepository (standings), PromotionRepository, DancerProfileRepository
UC-PUB-12 (1028, owner rule 2026-11-06: read the division catalogue, `GET /public/divisions`; cross-cutting W1 / W9: the create-event toggles and the public nav's directory links, the two screens that need the divisions before any other payload) ● BUILT
Service: DivisionCatalogueService (`catalogue()` -> `DivisionCatalogue {model_version, divisions[]}...
Domain Context: Division (shared kernel only: `DIVISIONS`, `DIVISION_HINTS`, `ENTRY_DIVISION`, `next_level...
Dependencies: none (constants; no repository); `public_cache_control`'s `CATALOGUE` tier sets the header, no `ETag`
Verified 2026-11-10: Built: GET /public/divisions feeds the create-event form and the public navigation. The matrix still says designed.
UC-ORG-13 (E11 conflict of interest) ● BUILT
Service: PromotionService (decider rule: organizer conflict -> App Owner, App Owner conflict -> PSA...
Domain Context: League & Stats (Promotions: decider eligibility as a pure rule), Access Control, Participa...
Dependencies: PromotionRepository, ParticipantRepository (triggering competition roster), OrganizationRepository (membership...
Verified 2026-11-10: Built in ticket 1028: the server decides who may approve and serves the reason. The matrix still says designed.
UC-OWN-05 ○ PLANNED
Service: PlatformSettingsService (`current`, `edit`, `history`; readers `promotion_thresholds`, `ra...
Domain Context: Administration (Platform Settings: versioned settings + immutable `SettingsChange` record)...
Dependencies: PlatformSettingsRepository (versioned item + change records, one transaction), AuditLogRepository
Verified 2026-11-10: Only a fixed, read-only settings provider exists. Nothing can be edited: no route, no screen.
UC-E11-01 ○ PLANNED
Service: My result read service (own entry, one row per round, published snapshots only; name fixed...
Domain Context: Publishing (published snapshots), Participant Management (own entry by account id / verifi...
Dependencies: ResultRepository (published snapshot per round), ParticipantRepository, CompetitionRepository (round plan)
Verified 2026-11-11: No code exists: the unused domain module was removed (ADR-1110, slice S11). No service, route or screen.
UC-AUD-02 (E11 couples-first final) ◑ BACKEND ONLY
Service: ResultsPublishingService (public payload: couples block for a criteria final, then per-rol...
Domain Context: Publishing, Final Show (draw couples), Dancer Profile (consented photos)
Dependencies: ResultRepository, FinalShowRepository (current draw), DancerProfileRepository (`get_cards`)
Verified 2026-11-10: The public results API returns the couples in order. No screen draws them.
UC-E14-08 ○ PLANNED
Service: ContentService (reserved, E14)
Domain Context: Editorial Content (reserved, E14), Access Control (`PlatformAuthority`), Administration
Dependencies: ContentRepository (reserved, E14), AuditLogRepository
Verified 2026-11-10: Only an unused domain module exists (backend/domain/content.py: quote rules). No service, route or screen. Designed for later (E14).
UC-E14-09 ○ PLANNED
Service: JudgeDirectoryService (reserved, E14)
Domain Context: Judge Directory (reserved, E14), Access Control (`PlatformAuthority`, self-certification c...
Dependencies: JudgeDirectoryRepository (reserved, E14), AuditLogRepository
Verified 2026-11-10: Only an unused domain module exists (backend/domain/judge_directory.py: judge name rules). No service, route or screen. Designed for later (E14).
UC-E14-10 ○ PLANNED
Service: ContentService (post hide/restore, reserved, E14), ProfileService (`DancerProfileService` ...
Domain Context: Editorial Content (reserved, E14), Dancer Profile (bio moderation), Access Control (`Platf...
Dependencies: ContentRepository (reserved, E14), DancerProfileRepository, AuditLogRepository
Verified 2026-11-10: Only an unused domain module exists (backend/domain/content.py: quote rules). No service, route or screen. Designed for later (E14).
UC-E14-11 ○ PLANNED
Service: ContentService (curated inductees, reserved, E14)
Domain Context: Editorial Content (reserved, E14), League & Stats (League History, reserved, E14), Access ...
Dependencies: ContentRepository (reserved, E14), LeagueRepository, AuditLogRepository
Verified 2026-11-10: Only an unused domain module exists (backend/domain/content.py: quote rules). No service, route or screen. Designed for later (E14).
UC-E14-12 ○ PLANNED
Service: ContentService (event gallery & highlight video links, reserved, E14)
Domain Context: Editorial Content (reserved, E14), Competition Management (event authority), Administratio...
Dependencies: ContentRepository (reserved, E14), CompetitionRepository, OrganizationRepository, AuditLogRepository
Verified 2026-11-10: Only an unused domain module exists (backend/domain/content.py: quote rules). No service, route or screen. Designed for later (E14).
UC-E14-13 ○ PLANNED
Service: JudgeDirectoryService (certified browse & contact request, reserved, E14)
Domain Context: Judge Directory (reserved, E14), Tenancy / Organization (organizer membership), Administra...
Dependencies: JudgeDirectoryRepository (reserved, E14), OrganizationRepository, AuditLogRepository
Verified 2026-11-10: Only an unused domain module exists (backend/domain/judge_directory.py: judge name rules). No service, route or screen. Designed for later (E14).
UC-E14-14 ○ PLANNED
Service: JudgeDirectoryService (opt-in profile & withdrawal, reserved, E14)
Domain Context: Judge Directory (reserved, E14), Dancer Profile (W8 photo consent), Access Control
Dependencies: JudgeDirectoryRepository (reserved, E14), StaffAccountRepository, DancerProfileRepository
Verified 2026-11-10: Only an unused domain module exists (backend/domain/judge_directory.py: judge name rules). No service, route or screen. Designed for later (E14).
UC-E14-07 ○ PLANNED
Service: ProfileService (`DancerProfileService` bio, reserved, E14)
Domain Context: Dancer Profile (optional bio, reserved, E14)
Dependencies: DancerProfileRepository
Verified 2026-11-10: No code. Designed for later (E14).
UC-E14-01 ○ PLANNED
Service: ContentService (published news & interviews reads, reserved, E14)
Domain Context: Editorial Content (reserved, E14)
Dependencies: ContentRepository (reserved, E14)
Verified 2026-11-10: Only an unused domain module exists (backend/domain/content.py: quote rules). No service, route or screen. Designed for later (E14).
UC-E14-02 / UC-E14-03 ○ PLANNED
Service: ContentService (public event gallery & highlight video links, reserved, E14)
Domain Context: Editorial Content (reserved, E14), Competition Management (Event Media)
Dependencies: ContentRepository (reserved, E14), CompetitionRepository
Verified 2026-11-10: Only an unused domain module exists (backend/domain/content.py: quote rules). No service, route or screen. Designed for later (E14).
UC-E14-04 ○ PLANNED
Service: LeagueService (history reads, reserved, E14; + ContentService curated inductees, ProfileSe...
Domain Context: League & Stats (League History, reserved, E14), Editorial Content (reserved, E14), Dancer ...
Dependencies: LeagueRepository (W7 standings/awards, E5 season ranking snapshots), ContentRepository (reserved, E14), Dancer...
Verified 2026-11-10: No record book and no curated inductees. The page /league/salon shows season champions (UC-E5-05).
UC-E14-05 ○ PLANNED
Service: LeagueService (history reads, reserved, E14; extends `UC-PUB-06` rankings + ProfileService...
Domain Context: League & Stats (Rankings / League History, reserved, E14), Dancer Profile
Dependencies: LeagueRepository (E5 season ranking snapshots, W7 standings), DancerProfileRepository
Verified 2026-11-10: No code. Designed for later (E14).
UC-E14-06 ○ PLANNED
Service: JudgeDirectoryService (public opted-in listing, reserved, E14)
Domain Context: Judge Directory (reserved, E14), Dancer Profile (consented public card), League & Stats (p...
Dependencies: JudgeDirectoryRepository (reserved, E14), DancerProfileRepository, LeagueRepository
Verified 2026-11-10: Only an unused domain module exists (backend/domain/judge_directory.py: judge name rules). No service, route or screen. Designed for later (E14).
UC-PUB-06 ● BUILT
Service: LeagueService (`rankings`, `ranking`; delegates snapshot/close reads to `RankingSnapshotSe...
Domain Context: League & Stats (Rankings: `RankingDefinition`, `build_rankings`; the E5 snapshot read types are planned)
Dependencies: LeagueRepository (`list_tables`, `list_standings_many`, `list_standings` per-division retry), RankingSnapshotR...
UC-DIR-05 / UC-DIR-06 / UC-DIR-10 (121 + E5 extension) ◐ PARTLY BUILT
Service: ScoringService (`lock_round`: dispatch by method), ResultsPublishingService (resolved snap...
Domain Context: Scoring (v2 calculation, tie cases), Round Progression (tie key = placement), Publishing, ...
Dependencies: ResultRepository, CompetitionRepository, LeagueRepository, RankingSnapshotRepository (E5), PromotionRepository...
Verified 2026-11-10: Lock, publish and advance are built. The step that writes a ranking snapshot after a publish is not registered, so a real publish writes none.
UC-E5-03 ◐ PARTLY BUILT
Service: LeagueService (`league_table`, `rankings`, `ranking`) -> RankingSnapshotService (`read_div...
Domain Context: League & Stats — Ranking Snapshots (`RankingSnapshot`, `SnapshotStep`, `SnapshotRow`, `Sna...
Dependencies: RankingSnapshotRepository, LeagueRepository, DancerProfileRepository, AuditLogRepository
Verified 2026-11-10: Movement and history are computed when read. Snapshots are written only by the dev demo seed. There is no dated ranking screen.
UC-E5-04 ◑ BACKEND ONLY
Service: RankingSnapshotService (`season_replay`)
Domain Context: League & Stats — Ranking Snapshots (`RankingSnapshot`, `SnapshotStep`, `SnapshotRow`, `Ran...
Dependencies: RankingSnapshotRepository, LeagueRepository, DancerProfileRepository
Verified 2026-11-10: A function with tests. No route and no screen.
UC-E5-05 ◐ PARTLY BUILT
Service: LeagueService (`season_champions`, `league_table`, `rankings`, `ranking`, `dancer_profile`...
Domain Context: League & Stats — Season Close & Ranking Snapshots (`SeasonClose`, `SeasonClosed`, `SeasonS...
Dependencies: RankingSnapshotRepository, LeagueRepository, DancerProfileRepository
Verified 2026-11-10: Viewing a closed season works. A season can be closed only by the dev demo seed, because the close route does not exist.
UC-E5-06 ● BUILT
Service: LeagueService (`my_league_summary`: the gap to the next place, computed on read)
Domain Context: League & Stats — Ranking Snapshots (`GapRead`, shared `"1224"` next-distinct-rank gap over...
Dependencies: RankingSnapshotRepository, LeagueRepository
Verified 2026-11-10: Built on the dancer's page from GET /me/league, computed in LeagueService without snapshots. The matrix still says designed.
UC-E5-01 ◑ BACKEND ONLY
Service: SeasonCloseService (`close`, `reopen`, `status`; `backend/application/season_close.py`) ->...
Domain Context: League & Stats — Season Close & Ranking Snapshots (`SeasonClose`, `SeasonClosed`, `SeasonR...
Dependencies: RankingSnapshotRepository, LeagueRepository, CompetitionRepository, ParticipantRepository, ResultRepository, A...
Verified 2026-11-10: SeasonCloseService can close and reopen a season. There is no route and no screen.
UC-E5-02 ◑ BACKEND ONLY
Service: RankingSnapshotService (`backfill_snapshots`)
Domain Context: League & Stats — Ranking Snapshots & Season Close (`RankingSnapshot`, `SnapshotStep`, `Sna...
Dependencies: RankingSnapshotRepository, LeagueRepository, CompetitionRepository, ResultRepository, AuditLogRepository
Verified 2026-11-10: The backfill method exists. There is no route; only the dev demo seed calls it.
UC-PSA-06 ◑ BACKEND ONLY
Service: PlatformGrantService (`grant`, E3-D5)
Domain Context: Access Control (`PlatformGrant`, `PlatformGrantEvent`, `PlatformAuthoritySource`)
Dependencies: PlatformGrantRepository (`PK = PLATFORM_GRANTS`: `GRANT#` + audit `EVENT#` + `META` in one transaction, E3-D4)...
Verified 2026-11-10: PlatformGrantService is written and tested. There is no route and no screen. Grants are written only by the dev demo seed; the PSA and App Owner ids come from stage configuration.
UC-PSA-07 ◑ BACKEND ONLY
Service: PlatformGrantService (`revoke`, E3-D5)
Domain Context: Access Control (`PlatformGrant`, `PlatformGrantEvent`)
Dependencies: PlatformGrantRepository (delete `GRANT#` + audit `EVENT#` + `META`), config `PSA_ACTOR_IDS` (last-PSA guard)
Verified 2026-11-10: PlatformGrantService is written and tested. There is no route and no screen. Grants are written only by the dev demo seed; the PSA and App Owner ids come from stage configuration.
UC-PSA-08 ◑ BACKEND ONLY
Service: PlatformGrantService (`list`, `history`, E3-D5)
Domain Context: Access Control
Dependencies: PlatformGrantRepository (consistent `Query` `GRANT#` / `EVENT#`), config `PSA_ACTOR_IDS`, `APP_OWNER_ACTOR_IDS...
Verified 2026-11-10: PlatformGrantService is written and tested. There is no route and no screen. Grants are written only by the dev demo seed; the PSA and App Owner ids come from stage configuration.
UC-CMP-09 ○ PLANNED
Service: RegistrationService (`withdraw_registration`, `channel=APP`)
Domain Context: Participant Management (`Competitor.withdraw`, `RegistrationExit`, `ExitKind.DANCER_WITHDR...
Dependencies: ParticipantRepository (`get_competitor`, `list_registration_exits`, `record_registration_exit`: ONE conditiona...
Verified 2026-11-10: Only the domain rules exist. No service method, route or screen.
UC-CMP-10 ○ PLANNED
Service: WithdrawLinkService (`issue` for E8, `preview`, `confirm` -> RegistrationService.`withdraw...
Domain Context: Withdraw Token (`WithdrawTokenClaims`, `WithdrawTokenRecord`, `sign_withdraw_token`, `veri...
Dependencies: SigningKeyProvider (`integrations/ssm_signing_key.py` SSM `SecureString` adapter), WithdrawTokenRepository (sl...
Verified 2026-11-10: Only token signing code exists (being removed, ADR-1110). No link route or page, and email cannot send.
UC-ORG-14 ○ PLANNED
Service: RegistrationService (`remove_registration`) + AuthorizationService (`event_authority`: fes...
Domain Context: Participant Management (`Competitor.remove`, `RegistrationExit`, `ExitKind.ORGANIZER_REMOV...
Dependencies: ParticipantRepository (`get_competitor`, `get_bib_owner`, `record_registration_exit`: ONE conditional transact...
Verified 2026-11-10: Only an enum value and a wording rule exist. No service method, route or screen.
UC-ORG-15 ○ PLANNED
Service: SignupInsightService (`ranked_signups`) over LeagueService (`dancer_id_for`, `league_table...
Domain Context: Participant Management (`Competitor.is_active_entry`, `rank_competition_signups`), League ...
Dependencies: ParticipantRepository (`list_competitors`), CompetitionRepository, OrganizationRepository, StaffAccountReposit...
Verified 2026-11-10: Only an unused domain function exists. No service, route or screen.
UC-REG-03 (E7 extension) ◐ PARTLY BUILT
Service: RegistrationService (`list_competitors`, `restore_competitor`, `scratch_competitor`)
Domain Context: Participant Management (`Competitor.exit_kind` / `exit_channel` / `last_exit_id`, `parse_e...
Dependencies: ParticipantRepository (`list_competitors`, `record_registration_exit` (a designed name: no such method exists yet; the code has `list_registration_exits`), `claim_competitor_email`, `claim_event_...
Verified 2026-11-10: Scratch and restore are built. A desk scratch writes no exit record, and no screen shows the exit kind.
UC-E1-01 (E1) ○ PLANNED
Service: none: pipeline / infrastructure (prod tag pipeline + release gate; `design/deployment/prod...
Domain Context: none (operations only)
Dependencies: `deploy-prod.yml` (planned, E1-D9), `jnj-prod-*` CDK stacks, post-deploy smoke (planned, E1-D11), `/health` re...
Verified 2026-11-10: Prod stage configuration and runbooks exist. There is no production pipeline: no deploy-prod workflow.
UC-E1-02 (E1) ○ PLANNED
Service: none: pipeline / infrastructure (re-deploy of a previous tag above the 122 floor; `design/...
Domain Context: none (operations only)
Dependencies: `deploy-prod.yml` (planned, E1-D9), `jnj-prod-*` CDK stacks
Verified 2026-11-10: The rollback runbook exists. There is no production pipeline.
UC-E1-03 (E1) ○ PLANNED
Service: none: infrastructure (PITR restore into a new table; `design/ops/restore-drill-runbook.md`...
Domain Context: none (operations only)
Dependencies: DynamoDB PITR on `jnj-prod-competition` (StorageStack), stage config for the table name (`design/infrastructur...
Verified 2026-11-10: Point-in-time recovery is on. The restore drill runbook is a proposal and no drill has been run.
UC-E1-04 (E1) ○ PLANNED
Service: none: backend startup config (`backend/api/shared/settings.py` reads `PSA_ACTOR_IDS` / `AP...
Domain Context: Access Control (`PlatformAuthority`, config only)
Dependencies: CDK context `psaActorIds` / `appOwnerActorIds` for `prod`, api-stack deploy (UC-E1-01)
Verified 2026-11-10: Per-stage admin ids exist in the CDK configuration. The rest is not built.
UC-E1-05 (E1) ○ PLANNED
Service: none: pipeline / infrastructure (go/no-go record checked by the release gate; `design/depl...
Domain Context: none (operations only)
Dependencies: release record (planned, E1-D15)
Verified 2026-11-10: A go or no-go checklist exists as a document. Nothing checks it.
UC-PII-01 (W15) ◑ BACKEND ONLY
Service: PersonalDataService (`request_erasure`, `cancel_erasure`)
Domain Context: Personal Data (`ErasureRequest`, `ErasureSubject`), Identity
Dependencies: ErasureRepository (`ERASURE#`, create-once, versioned)
Verified 2026-11-10: The dancer's request routes exist. No screen calls them.
UC-PII-02 (W15) ● BUILT · API OR TOOL ONLY
Service: PersonalDataService (`inventory`, `execute_erasure`) -> RegistrationService (`exit_for_era...
Domain Context: Personal Data (`plan_erasure`, `Tombstone`, `ErasureRefs`, `retained_reason`), Administrat...
Dependencies: every repository above (conditional, idempotent writes), S3 media deletion (E12 path), Cognito `AdminDeleteUse...
Verified 2026-11-10: A PSA operations API, run from the runbook. Deleting the Cognito account is a manual step. No content purge step exists.
UC-PSA-19 (ticket 1068 C5, ops) ● BUILT · API OR TOOL ONLY
Service: RoleClassSentinelService (`release_orphan_role_class_sentinel`: dry run lists orphans and ...
Domain Context: Access Control + Participant Management (`domain/role_class_sentinel.py`: who holds a sent...
Dependencies: RoleClassSentinelRepository (`DynamoDBRoleClassSentinelRepository`: the sentinel query, the release transactio...
UC-PSA-18 (ticket 1068 C2, ops) ● BUILT · API OR TOOL ONLY
Service: SeasonCloseService (`release_publish_in_flight`); LeagueService award run finishes an `EXC...
Domain Context: League (`SeasonClose.finish_publish`, `is_stale_publish`, the lease), Administration (audi...
Dependencies: SeasonCloseRepository (versioned put on `SEASON#`; `list_season_closes` in round 2), AuditLogRepository
Verified 2026-11-10: Built: the release route, the detect-only sweep and its alarm.
UC-PII-03 (W15) ● BUILT · API OR TOOL ONLY
Service: PersonalDataService (`list_requests`, `inventory`; `PERSONAL_DATA_READ` audit)
Domain Context: Personal Data, Administration
Dependencies: ErasureRepository, the participant / staff / request indexes (GSI2, GSI3)
Verified 2026-11-10: A PSA operations API.
UC-PII-04 (W15) ● BUILT
Service: RegistrationService (`list_competitors_view`) -> `api/roster/views.py` (`FLOOR_ROSTER_ROW_...
Domain Context: Participant Management (roster view)
Dependencies: ParticipantRepository
Verified 2026-11-10: The roster read returns the reduced row to a Floor Manager; the desk and director screens use the same read. No floor screen calls it: the floor screen reads heats only.
UC-E8-01 (W12 T1) ◌ DRY RUN ONLY
Service: EmailOutboxService (`enqueue_for_registration`, after-commit from RegistrationSer...
Domain Context: Email (Outbox, Consent), Participant Management
Dependencies: EmailOutboxRepository (`EMAIL_*` hashed keys, Wave 6 A1), SSM `SendModeProvider`
Verified 2026-11-10: Email cannot send on any stage: the send mode is dry run everywhere and no ses:SendEmail grant exists. In dry run no outbox row is written.
UC-E8-02 (W12 T2 / T3) ◌ DRY RUN ONLY
Service: ReminderWorkerService (`tick`) -> EmailOutboxService
Domain Context: Email (Reminder Planner, Outbox)
Dependencies: EmailOutboxRepository, EventBridge schedule (unscheduled), SSM
Verified 2026-11-10: Email cannot send on any stage: the send mode is dry run everywhere and no ses:SendEmail grant exists. No schedule ticks the email worker.
UC-E8-03 (W12 T4) ◐ PARTLY BUILT
Service: DeliveryEventService (`handle_sns_notification`, idempotent on `ses_event_id`)
Domain Context: Email (Suppression, Outbox)
Dependencies: SNS -> Lambda (neither exists yet), DeliveryEventRepository
Verified 2026-11-10: The handler and its repository exist. It cannot run: the worker factory always raises, and there is no SNS topic or SES configuration set.
UC-E8-04 (W12 T5) ◑ BACKEND ONLY
Service: EmailPreferenceService (`opt_out`, `record_admin_opt_out`, `add_manual_suppression`, `lift...
Domain Context: Email (Preferences, Suppression), Access Control
Dependencies: EmailPreferenceRepository, EmailSuppressionRepository, IdempotencyStore
Verified 2026-11-10: The admin routes exist. No screen calls them, the dancer's unsubscribe has no route, and sending is dry run everywhere.

Core System Invariants & Reliability Rules

Nine rules. Rules 01 to 08 are enforced by the code today, each checked against the code at the verified commit. Rule 09 is enforced on two of the three publish paths; its card says which one is open.

RULE 01
Identity vs. Authorization Separation
Amazon Cognito only signs people in and issues the ID token. Who may do what is decided from records in our own table (festival memberships, staff grants, platform grants) and from the PSA and App Owner ids in stage configuration. Cognito groups are not used.
RULE 02
Pure Domain Code
The rules (scoring, cuts, the couple draw, the level lock) are functions and records in backend/domain. No file there imports boto3, FastAPI or pydantic, and a test checks it. The domain tests run without AWS.
RULE 03
Automatic Registration Cutoffs
Self sign-up reads as closed once the event's deadline day has passed, or once the roster has been frozen. Nothing runs on a timer: the state is computed when it is read and checked again when an entry is written.
RULE 04
Staff Cannot Dance
A Judge, a Head Judge or a Competition Director cannot hold that job in a competition where they are also a competitor who is not scratched. The rule is checked when the job is granted and when the person registers, whichever comes second.
RULE 05
Conflict of Interest Shield
Anyone on a competition's roster, whatever their job (App Owner, organizer, director), cannot read its unpublished marks, the heat map or the ties until the results are published. The PSA is exempt. A judge who is not on the roster always reads their own card.
RULE 06
One Submit, Applied Once
A 1-10 or criteria card is sent with a submission_id minted once on the phone. A repeat of a submit the server already applied is acknowledged with no second write. The same marks sent again never raise the marks version.
RULE 07
Deploys Go Through CI
Today only dev is deployed, by GitHub Actions on a push to main (or a manual run of the same workflow) after CI passes. There is no production pipeline yet. The owner's rule for production, a version tag push and never a manual deploy, is designed and not built (UC-E1-01).
RULE 08
Two Divisions: Amateur & Pro
There are exactly two divisions, Amateur and Pro, and a division exists once per event. A dancer's level per role decides which division they may enter. Staff can place a dancer in the other division; placing a Pro dancer into Amateur needs a recorded reason.
RULE 09
One Publication Gate
The designed rule: results become public only after the tie gate has passed, and no tool publishes around it. What runs today: on rounds scored 1-10, and on every publish saved for the ceremony, the publish answers 409 TIES_UNRESOLVED and writes nothing while a tie that decides a place is open, and the head judge decides first. A publish that is already marked is only finished, never refused on a tie, so a round cannot be left with neither a result nor a way to decide. Every publish path has the gate: the one path without it left with the older card-based scoring in the direct route (piece 1, wave 3); the demo seed and the dev scenarios decide their ties through the real decision (scoring slices R4 and R5, built). On dev today, until the push, the older build still has that path: a known open defect, dev only.