One calendar for every squad in the building

One organization can run leagues in any of the 23 sports the platform supports, each with its own rules and scoring model, and there is no cap on how many sports an organization enables.

A sport must be explicitly enabled for the organization before leagues of that sport can be created — league creation returns 403 without a TenantSport row (backend/src/handlers/leagueHandler.ts:564). The Settings → Sports screen only adds sports; disabling is not exposed there and the API has no disable or delete endpoint, so a sport stays enabled once turned on.

A league can hold multiple seasons; admins can create, rename, activate and close seasons, archive a finished league to make it read-only, and roll it over into a new league that carries the same teams and division structure with no match history.

Exactly one season is marked current at a time, enforced in application code rather than by a database constraint. Archived leagues become read-only for teams, rosters, schedule generation and season changes. Roster carry-forward on rollover is opt-in.

Generate a full round-robin schedule for a league from its team list — the app pairs every team using the circle method, inserts a bye when the team count is odd, and writes the fixtures and matches in a single transaction.

League-admin action only (LEAGUE_ADMIN / SUPER_ADMIN / PLATFORM_SUPPORT, or a club role holding the LEAGUE_MANAGE_SCHEDULE capability — backend/src/handlers/standingsHandler.ts:310). Requires an active season (backend/src/services/scheduleService.ts:227) and at least two non-deleted teams (backend/src/services/scheduleService.ts:214). An archived league is read-only, so a closed season's schedule cannot be regenerated.

If you try to schedule or move a match into a window where one of the two teams is already playing, the app blocks the save and names the clashing fixture.

It is a soft block: an authorized league admin can force the booking through by re-sending with an override flag (backend/src/handlers/matchHandler.ts:1059). Bulk generation never blocks — it returns the overlaps as warnings instead (backend/src/services/scheduleConflictService.ts:288).

Scheduling a match into a window when the same venue is already hosting one raises a conflict that must be acknowledged before it saves.

The server-side check compares the venue only — it does not consider which court within the venue, so two matches on different courts of the same venue are reported as a venue conflict. Court-level precision exists only as an advisory banner in the browser's schedule manager (frontend/src/pages/app/schedulerConflicts.ts:78), which never blocks a save.

Split a venue into named courts or surfaces, and add, rename, delete or reorder them as the building changes.

Court names are a venue-configuration surface; assigning a court to a match is a manual choice in the match dialog, not an automatic allocation.

Create one-off matches by hand with a date, time, venue and court number, then move, postpone or cancel any match from the schedule manager.

Admin surface — the schedule manager route is restricted to SUPER_ADMIN, PLATFORM_SUPPORT and LEAGUE_ADMIN (frontend/src/app/router/router.tsx:812); a custom club role holding LEAGUE_MANAGE_SCHEDULE can move matches via the API. Cancel is a status change, not a delete — the row stays on the schedule and can be moved back to SCHEDULED or POSTPONED (backend/src/handlers/matchHandler.ts:1302). Deleting it is a separate action.

Scorekeepers get a dashboard listing the league's games in priority order — live first, then today, then the rest of the week — with one-tap entry into the console.

The file states there is no per-match scorekeeper assignment system today; every match in the league is visible to every scorekeeper (frontend/src/pages/app/ScorekeeperDashboardPage.tsx:5).

BallOBall ships a scorekeeper console for every one of its 23 supported sports, and the console for a given match is selected automatically from that match's sport.

Twenty-two sports render a dedicated sport-pack console; basketball uses the original ScorekeeperPage (frontend/src/sports/basketball/slots.ts:9 deliberately ships no console slot). The route is role-gated to SUPER_ADMIN, PLATFORM_SUPPORT, LEAGUE_ADMIN and SCOREKEEPER — coaches, players and fans cannot open it.

If the connection drops mid-game the scorekeeper keeps tapping: events are written to a durable on-device queue that survives closing the tab, and they are sent in order automatically when connectivity returns.

The queue protects events captured after the console has loaded. The service worker caches only public read endpoints, never authenticated data (frontend/src/pwa/runtimeCaching.ts:7), so a console cannot be opened cold with no connectivity. Deterministic failures — a 4xx — mark the queued row errored and surface it to the operator instead of retrying forever, and a write that cannot reach IndexedDB at all rejects rather than silently dropping the event.

Any recorded event can be undone from the play-by-play log; the server deletes the event and reverses its score and timeout effects in the same database transaction.

On a match already marked FINAL, undo is refused unless the caller is platform staff (SUPER_ADMIN / PLATFORM_SUPPORT) — a scorekeeper must ask for the match to be reopened. Archived leagues are read-only.

Once a scorekeeper ends the game, the server refuses any further scoring events on that match, so the official result cannot be moved after the book is closed.

Reopening a finalized match to score again is restricted to platform staff. The End-game dialog warns when locally queued events are still syncing, but finalizing is not blocked on the queue draining.

A full-screen scoreboard page opens in one click from the scorekeeper console, drags onto a second display over HDMI, and lets the operator show, hide, resize and reposition every element, with one-click Standard / Minimal / Detailed presets.

Layout choices are saved per match in that browser's localStorage, not on the server, so they do not follow the operator to another device. For a non-public league the page needs either a signed-in operator or the match's streaming toggle on, because the underlying match read answers 404 to an anonymous caller otherwise; the board then paints an access notice instead of a black screen, and keeps polling so flipping either switch brings it up without touching OBS.

Every league can publish a branded public page at balloball.com/l/<league-slug> that fans open in a browser.

Opt-in, not automatic: a league admin must flip the league to public (POST /leagues/{id}/visibility), which auto-enables the free PUBLIC_STATS module. Only leagues in ACTIVE or COMPLETED status are served; DRAFT and soft-deleted leagues 404. An unlisted league also 404s for anonymous visitors and for signed-in non-followers — only a signed-in follower (they redeemed the join code or accepted an invite) can read it.

Fans can open a public league page, its standings, schedule, teams, players and individual match pages in any web browser without creating an account or installing anything.

Following a league/team/player, the personalised feed, notifications, loyalty and ticket wallet all require a signed-in account.

A published league's fixture list and upcoming games are readable on its public fan page without signing in.

Gated on the league's SCHEDULING module (FREE tier, default on) plus the PUBLIC_STATS anonymous-read gate.

Anonymous fans can read a published league's standings table on its fan page.

Gated on the league's STANDINGS module. STANDINGS is a FREE-tier module that is enabled by default (backend/prisma/seed.ts:88), but a league admin can turn it off, in which case the tab disappears and the anonymous read returns an empty list.

Fans can subscribe a league, team, venue or single match schedule into Apple Calendar, Google Calendar or Outlook, and reschedules flow through to their calendar.

Public feeds honour the same public-league gate; private league feeds return 401 in the fan's calendar client. Each feed returns a sliding window of the last 90 days plus the next 365 days, capped at 1000 events.

Leagues can post news and announcements that appear on their public fan page.

Gated on the FAN_NEWS module (FREE tier, defaultEnabled true); a league admin can switch it off.

A league can stay off the public directory and still give its own followers full access to scores, standings and match pages via a join code or invitation.

Requires the fan to be signed in and to hold a follow row; anonymous visitors still get a 404 for an unlisted league.

Roughly a day before a scheduled match, every member of both teams is automatically reminded in-app, by web push and by email, on a scheduled job that runs continuously without an admin having to press anything.

Recipients are team members with claimed accounts, not league followers or ticket holders. Each match is reminded once, deduplicated. The sweep processes at most 200 matches per run (backend/src/services/pregameReminderService.ts:15) and honours the user's gameReminders toggle, so anyone who has switched that off receives nothing.

A coach or team captain can post an announcement to their team; it appears on the coach and player dashboards and fans out to each member's in-app inbox, web push, and email.

Editing, pinning and deleting an announcement are coach-only — a captain can post but not modify history (backend/src/handlers/teamFeedHandler.ts:1). Recipients must have a claimed user account; unclaimed roster entries are skipped.

Schedule team practices with a start time, duration and venue, and collect going / maybe / not-going responses from the squad.

Practices are created one at a time — the API has no recurrence or repeat rule, so a weekly practice must be entered per session.

Fans who follow a league can opt in to be notified when its matches go live and when they finish.

Requires an account and a follow row. Per-league opt-ins (notifyOnLive / notifyOnFinal) default ON when a fan subscribes, and the fan can turn each off. Delivery is fan-out on match status change; the in-app bell row is the canonical delivery, while web push and email are best-effort side channels — push is silently skipped without VAPID keys or a browser subscription, and email is sent for FINAL only.

A league admin can preview a composed weekly digest — standings leaders, top performers, recent results and upcoming fixtures — and send it by email to opted-in admins and followers.

MANUALLY TRIGGERED. There is no scheduled job that sends it automatically; an admin must open the league and press send (backend/src/handlers/leagueHandler.ts:2951, and the only comms cron — backend/src/handlers/commsTick.ts — runs campaigns, pre-game reminders and the recycle-bin purge, never the digest).

A league admin can compose one message to a chosen audience — everyone, admins, followers, or a specific team — pick email and in-app channels, preview the recipient count before sending, and see per-campaign sent / skipped / failed counts afterwards.

League-admin (or platform-root) only, and gated on the league's NOTIFICATIONS feature module, which 403s the whole surface when switched off (backend/src/handlers/messagingHandler.ts:129). The SMS channel is DORMANT in production — the Twilio secret still holds placeholder values, so an admin can pick SMS but every SMS recipient is recorded as skipped with reason not-configured rather than texted (backend/src/services/smsService.ts:29).

Divisions and pools can carry minimum and maximum age bounds, and the platform blocks adding an out-of-age player to a team in that division — both when an admin adds them to a roster and when someone registers.

Requires a birth date on the player; league admins and above can apply an explicit eligibility override.

Coaches, referees and volunteers can upload certifications, admins verify or reject them, and a compliance dashboard lists who across the organization is expiring soon or already expired.

Available to league admins and platform staff. Verification is a human admin decision on an uploaded document — nothing is checked against an issuing body.

A graduated multi-step return-to-play workflow lets staff file an incident, advance or set back a player through the stages, defer or clear them, and see which players on a team are currently in protocol.

Gated behind the MODULE_CONCUSSION_PROTOCOL feature module, which is seeded disabled by default and must be enabled per league. A player can always read their own incident history regardless.

League administrators can build and publish registration forms with custom questions, an optional waiver, fees, capacity limits and an open/close window.

Admin surface is role-gated to SUPER_ADMIN / PLATFORM_SUPPORT / LEAGUE_ADMIN (router.tsx:1006) and the league's REGISTRATIONS feature module must be enabled before the public form will accept anyone (registrationHandler.ts:1411).

A parent can open a shared registration link and sign a child up without creating an account.

Only works while the form status is PUBLISHED, the league is not archived, the open/close window is current, and the REGISTRATIONS module is enabled — otherwise the page shows a closed/not-found message (registrationHandler.ts:1409-1427).

A form can require a waiver; the registrant ticks acceptance and types a signer name, and the exact waiver text and its version are stored with the registration and can be viewed later.

Module-gated with the rest of registration. Signature capture is a typed name plus a checkbox, not a drawn signature or a third-party e-signature service.

Admins can paste rows or upload a CSV of players, preview the parsed result with per-row errors before committing, and see a per-row success/failure report with a retry for the failures.

Parsing and validation happen in the browser and rows are submitted one HTTP request at a time — there is no server-side batch endpoint, so a large import is a sequence of individual creates.

A league admin can hide player names from the public fan pages with a single setting, and the public API then omits them.

A per-league toggle; it is not a per-player consent flow and it does not retroactively remove names from anything already cached by a third party.

BallOBall ships a fixed set of roles — platform admin, platform support, league admin, coach, scorekeeper, referee, player, fan and a scan-only gate agent — and league admins can grant additional roles to members, including grants scoped to a single sport, league or team.

Roles are a fixed enum; organizations cannot define their own top-level roles. Sensitive listings (minors' ID documents, referee 1099 earnings, background-check results) require an organization-wide grant, because narrower club-scoped grants intentionally pass the coarse role check used for navigation gates — those endpoints call a separate tenant-wide guard that rejects a club-, league-, team- or sport-scoped grant.

Families and organization admins can store residency, medical, insurance and photo-ID documents against a household: the storage key is generated server-side and bound to the uploader with a signed token, the file is never given a public URL, and retrieval happens only through a short-lived signed link.

Access is limited to a guardian of that household, an admin of the household's organization, and platform staff. The underlying bucket uses S3-managed encryption with public access blocked; there is no customer-managed key option.

Guardians can be linked to and verified against a minor player, team messaging is checked against that policy before a message is stored, and admins get a review queue of policy violations they can resolve.

The policy currently LOGS violations rather than blocking them — the service's stated v1 contract always returns allowed, so no message is actually refused, and no notification is sent to the guardian when a violation fires. Hard-blocking is described in the code as v2 work behind a per-tenant flag that does not exist yet.

When the Team Comms module is enabled, every team chat message, announcement and logistics post is mirrored to a separate log that the service exposes only insert and read operations for, viewable and CSV-exportable by a league admin.

Gated behind the MODULE_TEAM_COMMS_V2 feature module, which ships disabled by default and must be turned on per league. Immutability is enforced by the service layer not exposing update or delete methods — it is not a database-level or cryptographic guarantee.

A user can delete their own account from within the app, and a minor's data can be exported or erased by the player, a verified guardian, an organization admin or platform staff — deliberately not behind any feature toggle.

Self-deletion is refused for staff accounts and for anyone who still owns an organization; ownership must be transferred first. Whole-organization export and user anonymization are platform-staff actions, not self-serve.

The production database is encrypted at rest with automated backups and deletion protection enabled, and uploaded files live in a versioned, encrypted bucket with all public access blocked.

AWS-managed encryption keys (S3-managed for objects, default RDS storage encryption) — there is no bring-your-own-key or customer-managed KMS option. Backup retention is configured at seven days. Everything runs in a single AWS region (us-east-2 by default), so there is no data-residency choice.