# Academy listings belong to registered Academies

The repository's architectural decision, rationale and consequences.

# Academy listings belong to registered Academies

**Status:** accepted, amended 2026-11-17 (see "Amendment: managed, never switched into") · **Date:** 2026-11-17 · **Amends:** US-30 (Academy listing, web)

**Enforcement:** the foreign key `academy_listing_academy_fkey`, `AcademyNotRegistered` in `academies.get` and `academies.save`, `requireRoleInInputOrganization` and `personalProcedure` (`packages/api/src/platform/rpc/procedures.ts`), `packages/db/src/academy-backfill.test.ts`, `packages/api/src/features/academies/academies.procedures.test.ts`, `packages/api/src/platform/rpc/rls.isolation.test.ts`, `packages/db/src/rls-catalog.test.ts` and `scripts/check-system-call-sites.mjs`.

Every signup gets a personal Organization (`org_<userId>`, the User is its owner, [ADR-0003](0003-organizations-are-the-tenant.md)). US-30 let the owner or admin of the Active Organization publish an Academy listing, so every Athlete could publish one from the workspace that exists only for their own training. A listing must come from an academy, and the database, not only the page, has to say which Organizations are academies.

## Decision [#decision]

**An Academy is an Organization with a marker.** The tenant table `academy_organization` (`organization_id` primary key and foreign key to `organization`, on delete cascade; `registered_by` to `user`, on delete set null; `created_at`) holds one row per Academy. It has RLS (`pgTable.withRLS`) with one tenant policy: SELECT where the context User is a Member of the row's Organization (`memberOf`), so the /academy page can list every Academy the User belongs to, not only the active one. `app_tenant` has SELECT and nothing else: tenant traffic cannot make an Organization an Academy.

**Only an Academy holds a listing.** `academy_listing.organization_id` references `academy_organization.organization_id` (on delete cascade) instead of `organization.id`. The database refuses a listing for any other Organization, on the system path too. `academies.saveMine` checks the marker first and fails with the tagged error `AcademyNotRegistered` (`FORBIDDEN`), so a caller gets a clear refusal instead of a constraint violation; the foreign key is the backstop.

**Registering creates a new Organization.** `academies.register({ name })` (name trimmed, 1 to 120 characters, as the listing name) runs on `userProcedure`: it needs a signed-in User but no Active Organization, re-reads the session from the database and refuses MCP access tokens, because it creates an Organization the User owns. In one system transaction under the new `SystemReason` `academies.register` ([ADR-0009](0009-row-level-security.md)) it writes the Organization (`aca_<32 hex>`, a slug from the name plus a random suffix), the caller's `owner` Member row and the marker, and returns the new `organizationId`. A per-User advisory transaction lock serialises concurrent registrations, and a User may register at most `ACADEMY_MAX_REGISTERED_PER_USER` (3, in the contract) Academies; the fourth fails with `AcademyRegistrationLimit` (`CONFLICT`). The registration is audited as `academy.registered` (target: the Organization) through `withAudit`.

**What the page sees.** `academies.getMine` returns `isAcademy` (the Active Organization has the marker), `canEdit` (an Academy and the caller is owner or admin), the listing (always null outside an Academy) and `academies`, the Academies the caller is a Member of with their names. Outside an Academy the web page explains that the personal workspace is for training, offers a "Switch to" button for each of the User's Academies and a "Register my academy" form; after registering, the web switches the Active Organization to the new Academy, so the editor appears.

**Grandfathering.** Production data is unknown, so the migration is non-destructive: `20261117072655_academy_organization_grants` inserts a marker (with `registered_by` NULL) for every Organization that already holds a listing before `20261117072717_academy_listing_requires_academy` moves the foreign key. Such listings stay as they are, published or not, and do not count toward anyone's cap. A NULL `registered_by` marks them, so the owner can review them by hand (for example, personal Organizations that published a listing before this change) and delete a marker, which removes its listing and schedule by cascade.

## Why not the alternatives [#why-not-the-alternatives]

- **A flag column on `organization`.** `organization` is Better Auth's table: an extra column means an `additionalFields` entry Better Auth then writes and exposes, and a column cannot be the target of the listing's foreign key on its own.
- **Refusing only the personal Organization (`org_` prefix).** It keys a rule on an id format, and any Organization a User creates through Better Auth (the Organization switcher) would still publish a listing.
- **Creating the Organization through Better Auth (`organization.create`) and then the marker.** Two requests, not one transaction: a failure between them leaves an Organization that is not an Academy, and the cap could not hold under concurrent calls.

## Consequences [#consequences]

- An Organization created in the switcher is not an Academy; only `academies.register` makes one. There is no "unregister": deleting the Organization removes the marker, the listing and its schedule.
- `academies.register` is the third reviewed system path of the feature (with `academies.public-read`); `packages/db/src/system-call-sites.txt` lists it.
- The Better Auth hook that audits `org.created` does not run for Academies; `academy.registered` is their audit event.
- Grandfathered markers (`registered_by` NULL) are left for the owner to review; nothing removes them automatically.

## Amendment: managed, never switched into (2026-11-17) [#amendment-managed-never-switched-into-2026-11-17]

Owner decisions D1 and D2 after review: Athletes do not understand workspaces, never switch Organizations, and an Academy is something a User manages, not a place they move into. This replaces "What the page sees" and the grandfathering of personal Organizations above.

- **No Active Organization in the product.** The web shows no Organization switcher or Organization settings. A new session starts in the User's personal Organization (`personalOrganizationOf`: owner of `org_<userId>` or the fresh `org_<userId>_<suffix>`), not in whichever membership comes first.
- **The season is the person's own.** `season.*` runs on `personalProcedure`, which resolves the personal Organization on the server (an identity read under `auth.membership`) and binds the tenant handle to it. The session's Active Organization plays no part, so a phone and a browser always read and write the same season.
- **Listings by Academy id.** `academies.getMine` and `academies.saveMine` are replaced by `academies.listMine` (the Academies the caller owns or administers), `academies.get({ organizationId })` and `academies.save({ organizationId, listing })`. `requireRoleInInputOrganization("owner", "admin")` reads the caller's role in the named Organization (FORBIDDEN otherwise) and binds the tenant handle to it, so the existing `inActiveOrganization` policies apply unchanged; the service still refuses an Organization without the marker (`AcademyNotRegistered`). The web lists them under Settings, "My academy", and edits one at `/academy/$academyId`.
- **Registering moves nobody.** `academies.register` leaves the Active Organization alone; the web opens the new Academy's editor.
- **Personal Organizations are never grandfathered.** The backfill moved to its own migration, `20261117072710_academy_listing_backfill`, after `20261117072700_academy_listing_held`. A listing held by a personal Organization (owned by the User its id names) moves, unpublished and with its schedule as JSON, to the system-only table `academy_listing_held` (RLS on, no policy, no grant); `academies.register` turns it into the listing of the first Academy that User registers, still unpublished, under the Academy's name. Every other Organization with a listing is grandfathered as before.

