Skip to content
Docs

Command palette

Jump to a page or view, or find a todo by name.

Changelog

Academy listings belong to registered Academies

The repository's architectural decision, rationale and consequences.

Markdown

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). 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

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) 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

  • 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

  • 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)

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.
Edit on GitHubDocumentation is in English.
Cookie settings
We use essential cookies to make our app work. With your consent, we also use optional cookies to improve your experience.

Read our Cookie Policy and Privacy Policy.