Data model#

A map of CrabbyTab's records for contributors: what each record is, its key fields, how records point at each other, and where they are stored. It is not a field-by-field dump; the source of truth is src/types/index.ts. Storage and sync are covered in depth in storage-and-scale.md and live-collaboration.md.

The big picture#

Tournament (settings in preferences)
├── Round ─────────────── Debate ── team slots by side ── Team ── Speaker[]
│                           ├── panel ── Adjudicator (conflicts[])
│                           ├── Venue
│                           ├── Motion
│                           ├── BallotSubmission (versions) ── speaker ids
│                           ├── FeedbackSubmission
│                           └── BallotIntakeRecord (paper sheets received)
├── Institution ◄── Team.institutionId, Adjudicator.institutionId
├── BreakCategory ◄── Team.breakCategories
└── AuditEvent (append-only)

Standings, the team and speaker tabs and most statistics are never stored: they are computed from rounds, debates and confirmed ballots whenever they are needed. The public site stores a pre-computed copy (see Public snapshots).

Tournament and settings#

Several small lists live inside preferences, not in their own collections:

There is no separate division record: teams carry divisionId / divisionName, and a round may carry divisionId.

Rounds#

drawStatus is none, draft, locked (confirmed, not public), teams_released, confirmed or released. confirmed and released both mean public (older data); read it through drawStageOf() in src/lib/draw/drawStatus.ts.

Participants#

Check-in fields shared by teams and adjudicators: checkedIn, checkedInAt, roundAvailability (round id → available), roundAvailabilityAt, checkInHistory[] (at, roundId, available, source, by).

Team–institution conflicts are on the team (institutionConflictIds); every other conflict is on the adjudicator. A mutual adjudicator–adjudicator conflict may be stored on one side only.

Debates (the draw)#

Sides are the keys of Debate.teams, and the same keys are used in ballots:

With the manual_ballot side rule, sidesConfirmed stays false until a confirmed ballot records which team took which side.

Results#

A debate's result is its one confirmed, non-discarded ballot. Older versions stay as history. A ballot whose teams no longer match the debate's slots never counts. Voting ballots hold the aggregated result at the top level and each adjudicator's sheet in sheets.

Breaks and audit#

Generating a break writes the result twice: on each team (breakStatus, breakCategoryIds) and as a snapshot on the category (generatedBreak).

Identifiers and references#

• Ids are opaque strings, unique within a tournament. New records get a prefix plus a random UUID from createEntityId (team-…, spk-…, adj-…, inst-…, ven-…, motion-…, bc-…); rounds, debates and ballots use their own patterns (round-…, debate-{roundId}-…, ballot-{debateId}-…). Never parse meaning from an id.
• Every tournament record has id and tournamentId. Speakers, conflicts and preformed panels are nested and have no tournamentId.
• Records point at each other by id. Names are copied next to ids (teamName, chairName, venueName, institutionName, motionText, …) for display; the id wins when they disagree.
• Speaker ids must stay stable: ballots refer to speakers by id. Imports and edits update speakers in place; a speaker with scores cannot be removed.

Where data is stored#

1. The working copy on the device#

Each tournament's working copy is in IndexedDB (database crabbytab, store kv; src/lib/offline/localStore.ts). Keys are crabbytab_t_{slug}_{suffix}, each holding a JSON string:

If IndexedDB is unavailable the same keys fall back to localStorage. Theme, language and remembered portal passcodes stay in localStorage. Separately, the Firebase SDK keeps its own persistent IndexedDB cache for live listeners and offline writes (src/lib/firebase.ts).

Local-only tournaments never leave the device. Cloud tournaments sync as described in Backups, restore and cloud sync.

2. Firestore#

The synced collections (CLOUD_COLLECTIONS in src/features/tournament/collections.ts) are rounds, teams, adjudicators, venues, motions, breakCategories, debates, ballots, feedback, institutions, auditEvents and ballotIntake. On administrator devices, ballots, debates, teams and adjudicators are also written and read live, record by record.

"Admin" below means a tournament administrator: the owner, a uid in admins, a staff member with role admin, or a global admin (custom claim globalAdmin). "Server" means server routes using the Admin SDK, which bypass the rules.

Debates in Firestore also carry a derived participantIds array (every team and adjudicator in the room) so private portals can query only their own debates. It is cloud-only: downloads strip it and sync hashing ignores it.

Cloud deletions are soft: the document stays with deletedAt set and a higher syncVersion, and the previous version is archived in syncConflicts.

3. Server-only documents#

Under tournaments/{id}/serverOnly/, read and written only by server routes:

4. Public snapshots#

Public pages never read the tournament collections. When an admin publishes (normally right after an upload), a server route reads the cloud copy and builds a projection (src/lib/publicView/projection.ts): an allowlist of fields from released data only (never emails, private URLs, passcodes or phone numbers), plus pre-computed tabs and aggregates (derived.ts). It is stored by src/lib/publicView/store.ts:

Sections are content-addressed, so an unchanged section is neither rewritten nor re-downloaded, and reads are served through the Vercel Data Cache. See Public pages and releases.

Sync fields#

File formats#

Changing the data model#

• Add new fields as optional and treat "absent" as the old behaviour: existing tournaments, backups and cloud documents do not have them. Many types document their "Absent = …" default in a comment.
• Older values stay readable (for example drawStatus: "confirmed", speaker categories stored as names, Venue.category without categories). Read through the helper named in the type's comment rather than the raw field.
• A new collection needs entries in CLOUD_COLLECTIONS, the backup validator, the device keys and, if public, the projection; check firestore.rules and the assistant and public projections for private fields.