🏠 Overview › 🧩 Components ›🧩 Role Guard Service

Role Guard Service

Component Detail

Service Layer high complexity mobilebackend
1
Dependencies
0
Dependents
32
Entities
0
Integrations

Description

Central authorization service that enforces role-based access boundaries across the mobile app and backend API. Evaluates the authenticated user's role (Peer Mentor, Coordinator, Organisation Admin, Global Admin) and organisation context against permission rules to determine access to screens, actions, and data scopes.

Feature: Role-Based Access Control

role-guard-service

Responsibilities

  • Evaluate user permissions against requested resource or action
  • Enforce route guards in Flutter navigation stack to prevent unauthorized screen access
  • Validate JWT role and organisation claims on every protected API endpoint
  • Handle multi-role users by applying permissions for the currently active role
  • Redirect Global Admin users to admin portal and display no-access screen in mobile app

Interfaces

canAccess(route: String): bool
canPerformAction(action: String, resourceType: String): bool
getPermissionsForRole(roleId: String): List<Permission>
validateApiRequest(jwtClaims: Map, endpoint: String, method: String): AuthResult
isRouteRestricted(route: String, role: String): bool
getAccessibleRoutes(role: String): List<String>
checkDataScope(role: String, organisationId: String, targetOrgId: String): bool
enforceMultiTenantIsolation(requestOrgId: String, targetOrgId: String): bool
getActiveRole(): UserRole
onRoleChanged(newRole: UserRole): void

Relationships

Dependencies (1)

Components this component depends on

data Permission Store

Sub-Components (2)

Route Guard
component medium

Flutter navigation guard that intercepts route transitions and checks the current user's role against the route's required permissions before allowing navigation.

  • Intercept navigation events and validate role permissions
  • Redirect unauthorized users to appropriate fallback screens
  • Support deep link validation against role constraints
API Permission Middleware
component medium

Next.js middleware that extracts JWT claims (role, organisation ID) and validates them against endpoint-level permission rules on every protected API request.

  • Extract and validate JWT role and organisation claims
  • Enforce endpoint-level permission checks
  • Return 403 responses for unauthorized requests with structured error messages

Related Data Entities (32)

Data entities managed by this component

Contact 22 fields core Event 19 fields core Note 16 fields core User 21 fields core User Role 11 fields configuration User Role Assignment 11 fields core Achievement Types 17 fields configuration Activities 24 fields core Activity Approvals 14 fields core Annual Summaries 26 fields derived Assignment Threshold Configs 18 fields configuration Assignments 27 fields core Bufdir Reports 25 fields core Contact Caregivers 17 fields core Contacts 24 fields core Course Registrations 17 fields core Courses 24 fields core Documents 20 fields core Event Registrations 14 fields core Events 27 fields core Expense Approvals 13 fields core Expense Types 25 fields configuration External Links 14 fields configuration Feature Flags 10 fields configuration Local Associations 17 fields core Notes 11 fields core Organizations 25 fields core Sessions 16 fields core User Local Associations 11 fields core User Role Assignments 12 fields core User Roles 13 fields core Users 26 fields core