Role-Based Access Control

high complexity MVP extracted Authentication & Access Control Confidence: 100%

Components

Shared

User Stories

Yes

Analyzed

Description

Role-based access control enforces which capabilities, screens, and API endpoints each authenticated user can access based on their assigned role within an organization. The system recognizes four roles: Peer Mentor, Coordinator, Organization Admin, and Global Admin, each scoped per organization so a user may hold different roles in different tenants. The Role Guard Service evaluates role membership on every API request; the Flutter Module Registry Service uses the role from the session bootstrap to assemble the correct navigation at runtime. This is a non-negotiable MVP component because every feature depends on knowing who a user is and what they may do.

Sources & reasoning

The Core Roles & Access Boundaries section defines four roles with strict access boundaries and tenant isolation requirements. The Fase 1 MVP scope in §5 explicitly includes role-aware mobile surfaces (two role profiles) and admin portal login roles, confirming Phase 1 = MVP placement. RBAC is a structural prerequisite for every other area in the platform.

No source references — this artifact was included based on reasoning alone (see above).

Analysis

Business Value

Without role-based access control the platform cannot enforce the operational boundaries required for safe multi-tenant operation. A peer mentor must not access another organization's data; a coordinator must not approve their own expense claims; a Global Admin must not read an organization's operational data without explicit time-bounded consent. These constraints are not optional - they underpin data protection obligations for organizations handling sensitive health and social care information. Correct RBAC also enables the Admin Web Portal to surface the right management UI per admin role without brittle conditional logic scattered across the application.

Implementation Notes

Roles are stored in the user_organization_roles join table linking users to organizations with a role enum. Role claims are embedded in the JWT at issuance so the backend can enforce access without an extra DB lookup on every request. The Role Guard Service on the backend returns 403 for requests exceeding the caller's role. The Flutter Module Registry Service reads the role from the session bootstrap response and mounts only the navigation, home widgets, and entry points permitted for that role - Coordinator and Peer Mentor see different home surfaces. Global Admin carries no organization context by default; time-bounded support access is gated by a flag in organization_settings and every such session is written to audit_logs. Role assignment changes take effect on the next token refresh.