Repository navigation
Description
Goal
Each Person is one record in the backend, and a record can be:
- a Group Admin;
- a Capo Admin;
- a member or Lead of one or more teams.
When the record is linked to a login account, these assignments are RBAC roles held in Auth.
When it isn't linked yet, they wait in the backend as pending assignments, and Auth knows nothing about the person.
Roadmap: PoliNetworkOrg/admin#146. Phase 1: PoliNetworkOrg/admin#143. Auth side: PoliNetworkOrg/auth#78.
Data model
All People data is test data, so drop the existing tables and recreate them. Nothing is migrated.
Proper tables replace the single JSON state with an advisory lock from #83:
- persons: id; first and last name; contact email; optional phone; optional Telegram username (informational only); notes;
account_sub(nullable, unique); created/updated by and at.- The contact email is only for sending invites. It is never used to match accounts.
- assignments: person; kind (
admin|capo|team); team key; team role (member|lead); since; ended; end reason;assigned_by(the sub of whoever made it); status.- Status values:
pending(record not linked),sent(waiting for Auth),applied,refusedwith Auth's reason.
- Status values:
- Capo of reference for each admin, as a relation to the Capo's person record, not free text. Capo scope (e.g. "Ingegneria Informatica") is a field on the
capoassignment.- This lets a future rule "a Capo Admin manages the admins under them" work out who is under whom. That rule isn't built now (see [People · Phase 1] Group Admins, Capo Admins and Team members with Auth roles admin#143).
- activity: append-only history of changes.
- invites: used by [People · Phase 1] Link records to accounts by email invite or manually #102.
Teams: keep it, hr, design, intl, events as config, but check it against Auth's bindings. A team without bound roles can't be assigned.
Where the truth lives
- Linked record: Auth is the source of truth.
- People reads who holds bound roles from
GET /api/internal/people-rolesand caches it. Keep feat(people)!: manage Auth-backed people before and after their first login #99's behaviour: a short TTL, and the last answer during short outages. - A change is a role command sent through the outbox (
POST, idempotentid, actor = the dashboard user). Until Auth confirms it, the change shows as waiting for Auth; if Auth refuses, show its reason.
- People reads who holds bound roles from
- Someone holding a bound role in Auth without a record (e.g. assigned by hand in Auth): create a record for them automatically, already linked.
- Unlinked record: assignments stay
pendingwithassigned_by. Nothing is sent to Auth until the record is linked ([People · Phase 1] Link records to accounts by email invite or manually #102).
Authorization in the backend
This is the gate for the dashboard and for pending assignments. Auth re-checks every role change when it's applied.
- Read:
admin:access+people:read. - Create or edit records, and assign Admin / team member:
admin:access+people:write, or being Lead of that team (for that team's members). - Appoint or end a Lead or Capo Admin:
admin:access+people:appoint. - My area:
people:self. - Pending assignments: Auth only sees these at link time, so the backend must apply the same rules as Auth (
peopleRoleChangeProblem) when they're made:- no assigning yourself;
- the right permission per kind;
- bounded delegation, checked against the role's permissions from the access snapshot (feat(access): project effective roles and the catalog in the backend snapshot auth#62 gives the backend the catalog).
- Keep these rules shaped like Auth's (one rule per kind), so a future Capo rule is added the same way on both sides.
Reuse from #99
- Reuse:
src/people/roles.ts(reading the role directory, the outbox to Auth, revision handling) and its tests. - Don't reuse:
identity.tsandlinking.tsmatching, reading the Soci group, and the preliminary-person code.
Done when
- Procedures exist for persons, admins, Capo Admins, teams and My area, and the npm package exports their types.
- Tests cover:
- pending vs linked records;
- a refusal from Auth showing on the record;
- automatic records for people assigned by hand in Auth;
- the Capo-of-reference relation;
- idempotent retries;
- Auth outages;
- pending-assignment authorization matching Auth's rules.
- Deployed after the IdP setup [People · Phase 1] Configure People role bindings in the production IdP auth#79 and after the cleanup [People · Cleanup] Remove Soci, fees, receipts, census and record matching from the People API #100.
Activity
coderabbitai commentedon Oct 29, 2026
🔗 Related PRs
#95 - feat(people): mirror PoliNetwork Auth roles and Microsoft 365 members [open]
📝 Issue Planner
Check the box below or use the
@coderabbitai plancommand to generate an implementation plan and prompts that you can use with your favorite coding assistant.🧪 Issue enrichment is currently in open beta.
You can configure auto-planning by selecting labels in the issue_enrichment configuration.
To disable automatic issue enrichment, add the following to your
.coderabbit.yaml:💬 Have feedback or questions? Drop into our discord!