ADR-0023: Platform team as a separate identity behind staff functions
- Status: Accepted
- Date: 2026-11-12
Context and problem statement
Section titled “Context and problem statement”The team that operates the platform uses a panel at /admin to list companies, switch modules on and off for a company, record the SMS registration status of a company and mark compliance rules as validated (ADR-0019). That work crosses companies, which the isolation of ADR-0002 forbids to every company user.
Who is a member of the platform team to the system, and how does the panel reach data?
Decision drivers
Section titled “Decision drivers”- A company account, however privileged, can never become a platform account.
- The API role still cannot bypass row level security.
- Everything the panel can do is a closed list.
- Every act of the team on a company is visible to that company.
Considered options
Section titled “Considered options”- Own tables, sessions and cookie for the team, and a
staffschema of definer functions that check the session inside the database. - Reuse the user and session tables with a type column. Rejected: the API can insert ordinary sessions, so a platform session could be created the same way. With two tables a token is valid in only one of the two worlds.
- Put the panel functions in the
gateschema with its owner role (ADR-0003). Rejected for least privilege: a separate schema and a separate owner. - A super-administrator flag that bypasses row level security. Common market shortcut, excluded by the second driver.
Decision outcome
Section titled “Decision outcome”Chosen option: 1.
Members are rows of platform_staff, with no link to company users. The role ochema_staff owns the staff.* functions and cannot log in. Every function receives the hash of the session token and checks the session itself, so there is no session setting that the API could set on behalf of the team. Signing in requires a proof of the password that the database verifies: no function creates a platform session without it.
The panel session lasts 12 hours and ends after 30 minutes without use. Its cookie is separate from the company cookie and is SameSite=Strict, and the /admin routes accept only requests whose origin is the office system. An invitation is valid for 24 hours. The first member is created from the command line.
Acts of the team are written to platform_audit_log. An act that changes a company also writes a row in the audit log of that company, shown as “Ochema platform team”.
In the API, panel controllers exist only in apps/api/src/modules/platform/admin. Lint forbids that folder to import company tables or the company context, and the API refuses to start when a route is marked on the wrong side of the boundary.
Consequences
Section titled “Consequences”- Good, because the two kinds of account share no table, no session and no cookie.
- Good, because the capabilities of the panel are the list of
stafffunctions, each one tested. - Bad, because every new panel feature needs a database function, delivered by a migration.
- Bad, because the team has a single role: every member can do everything the panel offers.
- Bad, because there is no password recovery by email for the team.
More information
Section titled “More information”packages/db/src/schema/platform-staff.tsandpackages/db/src/staff.ts: the tables and the typed wrappers of the functions.packages/db/migrations/0008_wave01_functions.sql: thestafffunctions.apps/api/src/core/auth/staff.guard.tsandroute-boundary.ts: the guard and the start-up check.apps/api/eslint.config.js: the import restrictions of the panel code.packages/db/test/staff-*.test.tsandapps/api/test/admin-*.test.ts: the tests.- Concept pages: Authentication and permissions, Audit log, Tenant isolation.