Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

02 — User Personas (Audit Module)

Roles, goals, permissions, and expected behaviour for every consumer of the Audit module. Permission values are exact from rbac/schemas/role.schema.ts (DEFAULT_ROLES) and rbac/permissions.constants.ts:54 (audit.read). Critical nuance: the server enforces only JwtAuthGuard on GET /audit-logs (audit.controller.ts:9) — audit.read is metadata today; the client gates on it anyway (Phase-5 (planned), docs/IMPLEMENTATION_PLAN.md:241; OQ-5 in 01).

1. Org Admin (org_admin) — primary user

AttributeValue
PermissionsALL_PERMISSIONS incl. audit.read (role.schema.ts:23)
FrequencyDaily to weekly; desktop/tablet during school operations
Goal"What changed, by whom, when?" — dispute resolution (fees, marks, attendance), staff oversight, verifying destructive actions
Pain pointsCan't find the exact entry (no search/date filter today), actor names not in the response, no export
Core jobOpen audit list → filter by action/actorId → tap an entry → read who/when/what changed
ExpectedRealtime new entries appear (WS); occurredAt shown in local time; immutable entries — no edit/delete affordances
Mental model"A tamper-proof diary of the school's system."

2. Compliance Officer (custom role, audit.read + report perms)

AttributeValue
PermissionsCustom role; must include audit.read (permissions.constants.ts:54); roles are per-tenant (role.schema.ts:68-85)
FrequencyMonthly/quarterly compliance windows; ad-hoc on disputes
GoalProduce a defensible record for a period: who touched student/fee records, when, with what before/after state
Pain pointsNo date-range filter ((planned)), no export ((planned)), before snapshots mostly absent (OQ-1)
ExpectedFilter + review + export (CSV/PDF, AUDITING.md:87) (planned); the audit itself logs the export action per blueprint
Mental model"Evidence for an inspection."

3. External Auditor / Inspector (invited access (proposed))

AttributeValue
AccessNot a first-class identity today — backend has no auditor persona (only `user
GoalVerify no unauthorized change occurred; spot-check entries against school records
ExpectedSame list/detail UI; must be able to prove integrity ("never modified") — UI communicates immutability (no edit/delete affordances, timestamp authority)
Mental model"Show me the paper trail."

4. Platform Admin (platform_admin, cross-tenant)

AttributeValue
Permissionspermissions: [] but JwtAuthGuard sets isPlatformAdmin=true when role present (jwt-auth.guard.ts:54) — bypasses seed
FrequencyOn-demand support / incident response
GoalCross-tenant visibility: did tenant X see tenant Y's data? correlate incidents via correlationId
RestrictionsPlatform audit entries (tenantId: null, actorType: platform) are not implemented (AUDITING.md:70-71 vs audit-log.schema.ts:7-11) — cross-tenant audit UI is (planned) (OQ-3)
ExpectedRead the tenant's audit log with a tenant-scoped token; per-tenant navigation (planned)
Mental model"Look under the hood across tenants."

5. Support / QA Engineer (internal)

AttributeValue
AccessTenant token with audit.read (or dev tooling)
GoalReconstruct a failed flow: follow correlationId (audit-log.schema.ts:51-52) from an error requestId to the audit entry
ExpectedcorrelationId visible on entry detail; copyable for issue reports
Mental model"The audit log is the debug trail."

6. Role → audit-appearance matrix

Valueorg_admincompliance officerauditor (proposed)platform_adminteacher/staff/accountant/parent/student
audit.read permission✓ (role.schema.ts:23)via custom rolevia custom rolen/a (platform flag)✗ (not in any seed role, role.schema.ts:31-42)
Server guard todayJWT only (audit.controller.ts:9) — no perm checksamesamesameJWT only — currently can read (OQ-5)
Client route gate✓✓✓✓hidden
Filter + list✓✓✓per-tenant (planned)—
Entry detail / diff✓✓✓——
Export(planned) (AUDITING.md:87)primary needprimary need——
Realtime append✓ (WS)✓✓——

Note: until the Phase-5 permission audit lands (docs/IMPLEMENTATION_PLAN.md:241), the server allows any authenticated user to read the tenant audit trail; the client hides the surface unless audit.read is present. Flag to security owner (OQ-5).