Roles & permissions

Access in Piranha is a role granted at a scope. A grant answers three questions: who (the account), what (the role, which maps to a fixed set of permissions), and where (the scope — the whole site, a league, a team, a meet, or an athlete). Grants cascade down: a league grant covers that league’s teams and meets; a team grant covers the meets that team swims in.

The roles

Role	Granted at	What it’s for
Site admin	site-wide	Everything, everywhere. The first CLI-created account is one.
League admin	a league	Everything within that league’s subtree — rulebook, teams, templates, meets, users.
Team admin	a team	Run the team: its info and pool, its roster, its participation in meets, creating meets, inviting/managing the team’s users.
Meet admin	a meet	Run one meet end to end: edit, seed, results, DQs, scoring, participants, exports.
Clerk	a meet	Deck operations: check-in/seeding adjustments, entering results, scoring.
Judge	a meet	Recording DQs (plus read access).
Coach	a team	The team’s roster and meet participation, plus exports.
Team director	a team	Read access to the team’s meets/results plus downloads (e.g. verifying entries).
Parent / Swimmer	an athlete	Read access and downloads for their own swimmer(s).

Every meet-facing role also carries the read permissions (meets, rosters, results, records). Public read-only views need no account at all — see Public views.

The common scenario: one login per team

Give each club a team admin on their own team:

1. Admin → Users: create the user (leave the password blank to make it an invited account) and send them the invite link.
2. On that user, open Manage roles → grant team_admin → pick their team.

They can now import and fix their roster, enter their swimmers in the meets their team participates in, create meets, and invite additional users for their own team — and nothing outside it.

For run-day helpers, grant clerk or judge scoped to just that meet.

Delegation is bounded

Granting a role requires holding user.manage over the target scope, and only a site admin can mint site or league admins. Nobody can escalate past their own subtree — a team admin can’t touch a site admin’s account, and can’t grant themselves league-wide powers. Admins also can’t lock themselves out by revoking their own last admin grant.

Granting from the CLI

The user-admin CLI mirrors the UI for scripted setups:

pnpm run user-admin grant --username coach_amy --role team_admin \
  --scope-type team --scope-id <team_id>
pnpm run user-admin roles --username coach_amy