Role-Based Access Control

RBAC is the structural backbone of the entire platform's security and multi-tenancy model. Without it, peer mentors could access coordinator functions, coordinators could modify organisation settings, and organisation data could leak across tenants - all of which would be catastrophic for GDPR compliance and organisational trust. The clearly defined role boundaries also simplify onboarding: each role sees only what is relevant to their responsibilities, directly reducing cognitive load for peer mentors with beginner-level digital skills. Global admin tenant isolation is a critical commercial requirement for selling the platform to multiple independent organisations.

Roles and permissions are stored in the PostgreSQL user_roles table, with role claims embedded in the JWT payload at login. The Next.js API uses middleware to validate role claims on every protected route. The Flutter app reads role claims from the decoded JWT to conditionally render navigation items and screens. The user_roles table supports multiple roles per user within different organisations, enabling coordinators who are also org admins in another association. A permissions matrix document should be maintained alongside the code. Role changes take effect on the next token refresh cycle; immediate revocation requires token invalidation via a server-side denylist.