Julien Gautier
bd8a13acb8
First PR of the portal-admin User-list chantier per ADR-0020 §"v1
scope — User list (read-only)". Ships the write side only:
- a `public.users` table that holds the BFF's local cache of
identities seen sign in to either portal-shell or portal-admin,
- a `UserDirectoryService.recordSignIn(user)` upsert called from
`SessionEstablisher.establish` AFTER the blocking audit write.
The read side (`GET /api/admin/users` + the admin viewer SPA
screen) lands in subsequent PRs of the chantier.
Schema
- `public.users` model in `schema.prisma`. Primary key on `oid`
(Entra's stable per-user identifier inside the tenant — the
natural choice; per-tenant uniqueness is sufficient for the v1
single-workforce-tenant design per ADR-0008).
- Columns: `oid`, `tid`, `audience`, `username`, `display_name`,
`first_seen_at` (default NOW, never overwritten), `last_seen_at`
(default NOW, updated on every upsert).
- Indexes: `last_seen_at DESC` for the admin "most recently
active" default sort, plain `username` for prefix filtering.
- Migration in `prisma/migrations/20260514192014_users_directory/`.
UserDirectoryService
- `recordSignIn(entry)` issues `prisma.user.upsert({ where: { oid },
create: {...}, update: {...} })`. Create sets `first_seen_at` +
`last_seen_at` via the DEFAULT clauses; update touches
`last_seen_at` + every mutable identity field but NOT
`first_seen_at`.
- Best-effort: catches its own errors, logs a Pino warn
(`user_directory.record_sign_in_failed`) and returns
`undefined`. The directory is a convenience for admin browsing,
not a security boundary — a Postgres hiccup must not lock a
user out of sign-in. ADR-0013's "no audit ⇒ no action" applies
to the audit module only.
SessionEstablisher wiring
- Calls `userDirectory.recordSignIn` AFTER `audit.signIn` so an
audit failure short-circuits the directory write (audit-first
invariant per ADR-0013). The await ensures the upsert completes
before the response is sent — an admin who just signed in sees
themselves on the user list immediately, without racing the
response.
- v1 hardcodes `audience: 'workforce'` per ADR-0008's single-
workforce-tenant simplification. Will read the real audience
from the session/claims when External ID activates.
Module wiring
- `UsersModule` declared `@Global()` so `SessionEstablisher`
(which lives in `AuthModule`) injects `UserDirectoryService`
without re-routing the module graph through an import. The
directory is a true cross-cutting concern: one writer (auth
callback), one future reader (admin endpoint).
- Wired into `AppModule` alongside the other v1 modules.
Tests: +7 specs (UserDirectoryService 4, SessionEstablisher
integration 3 — directory called with the right payload, called
AFTER audit, NOT called when audit fails, audience pinned to
workforce).
Pre-existing test updates: `auth.module.spec.ts` now imports
UsersModule (slice-of-graph compile would otherwise fail to
resolve SessionEstablisher's new dep); `auth.controller.spec.ts`
passes a noop directory mock to the SessionEstablisher
constructor — kept noop because that spec's behavioural surface
is about the controller path, not the directory.
Documentation index
This is the entry point to all project documentation. It is maintained automatically: any addition, rename, or removal of a .md file under docs/ must be reflected here in the same change.
Conventions
- Documentation is written in English.
- One topic per file. Group related files into a folder when there are three or more.
- Cross-reference with relative links so they keep working in GitHub, IDEs, and exported sites.
- For architectural decisions, do not add them here — they belong in decisions/ as MADR 4.0.0 ADRs.
Sections
Daily development
- development.md — repo layout, prerequisites, initial setup, daily commands, observability dev-loop (Jaeger UI, log ↔ trace correlation), dependency updates (Renovate), conventional commit cycle. Day-to-day reference for working on the project.
Architecture
- architecture.md — cross-cutting Mermaid diagrams: C4 system context, C4 containers, Nx module boundaries, CI/CD pipeline. Single-decision diagrams (auth sequence, ERD, etc.) live inline in their ADR.
Onboarding & environment
Setup guides for new contributors:
- setup/01-wsl-terminal-setup.md — modern WSL terminal (Zsh + Powerlevel10k + CLI tools)
- setup/02-dev-web-stack.md — Node via nvm, pnpm via corepack, Docker
- setup/03-angular-nx-monorepo.md — Angular + Nx monorepo bootstrap
Operations & runbooks
Empty — to be populated when we deploy.
Security, performance, accessibility
Empty — placeholders to be filled with rationale docs alongside their corresponding ADRs.