| Use case: step | Operation | State change | Refused, 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. |
Click any diagram header to collapse or expand. Every name in these diagrams exists in the code at the verified commit.
Scope: the people, the app in scope, and the external systems it really talks to
┌────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ 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.
Scope: Deployable runtimes, data storage units, client containers, and communication protocols
[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.
Scope: Internal modular decomposition of the Serverless Application Backend (FastAPI Lambda Container)
┌────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ 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 │ │
│ └────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ │
└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
Scope: Part 1 - Domain Bounded Contexts & Aggregate Roots | Part 2 - Persistent Model Overview (ERD & Cardinality) | Part 3 - DynamoDB Single-Table Schema
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.
Scope: one 1-10 or criteria card from the judge's phone to the one transaction that stores it
[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. │
Scope: the judge's outbox after the signal returns. It sends one card per request to POST /scorecards/{id}/submit. Delivery is not guaranteed
[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. │
Scope: the shared dev site only (never production): where its data comes from, how to tell the kinds apart, what keeps it safe
[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
| 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.
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.
[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
| 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 |
| 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) |
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.pybackend/domain/registration_level.pybackend/domain/dancer_directory.py |
DancerAccountProfile (root, one per account)RoleLevelProfileEventPublicDancerCard |
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.pybackend/domain/round_progression.pybackend/domain/competition_cancellation.py |
Competition (root: one division of an event)RoundPlannedRoundAdvancementDecision |
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.pybackend/domain/competitor_status.pybackend/domain/registration_level.py |
CompetitorCheckInEventRosterFreeze |
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.pybackend/domain/final_show.py |
HeatHeatAssignmentPartnerDrawFinalShow |
HeatStatus (READY, CALLED, COMPLETED, PAUSED)FloorCapacityDrawnCouple |
• 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.pybackend/domain/scoring_v2.pybackend/domain/scoring_v2_results.pybackend/domain/scoring_rule.pybackend/domain/judge_review.py |
ScorecardResultSetTieBreakDecisionJudgeExclusionCoupleWithdrawal |
ScoringMethodSnapshot (NUMERIC, CRITERIA; names its result rule, PANEL_AVERAGE 1)ScoreScale, Criterion, TieCaseScorecardStatus (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.pybackend/domain/promotions.pybackend/domain/rankings.pybackend/domain/season_close.py |
PointsAwardStandingLeagueTablePromotionSuggestion |
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.pybackend/domain/platform_grants.py |
StaffAssignmentStaffRevocationPlatformGrant |
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.pybackend/domain/organizer_requests.py |
Organization (a festival)OrganizationMembershipOrganizerRequest |
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. |
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) |
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.
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.