Define Role domain model and typed records
epic-role-based-access-control-data-infrastructure-task-004 — Create the typed Role domain model in Dart including fields for roleId, userId, roleName (enum: peer_mentor, coordinator, org_admin), orgId, orgUnitId, and isActive. Implement fromJson/toJson serialization and equality operators. Define the RoleAssignment value object that the repository layer exposes to the service layer.
Acceptance Criteria
Technical Requirements
Implementation Notes
Use Dart's built-in const constructors where possible for RoleAssignment to allow compile-time constant role assignments in tests. Implement == using roleId only (not all fields) since roleId is the stable identity — this prevents issues if isActive is updated without recreating the object. For copyWith(), generate all fields explicitly rather than using a code generator to keep the domain layer dependency-free. The RoleName enum's fromString() should be a static method on the enum using a switch expression (Dart 3+) for exhaustiveness checking.
Place RoleName in role_name.dart and RoleAssignment in role_assignment.dart within lib/domain/role/.
Testing Requirements
Write pure Dart unit tests (no WidgetTester needed) covering: RoleAssignment.fromJson() with all fields populated, RoleAssignment.fromJson() with orgUnitId null (optional field), RoleAssignment.toJson() produces correct snake_case keys, two RoleAssignment objects with the same roleId are equal via ==, RoleName.fromString('peer_mentor') returns RoleName.peerMentor, RoleName.fromString('invalid') throws ArgumentError. All tests should run with dart test or flutter test in under 1 second.
The get_my_roles RPC call adds a network round-trip immediately after login, potentially increasing the time before the home screen renders. If Supabase RPC is slow or the roles table lacks proper indexing, users with multiple org affiliations could experience noticeable delays.
Mitigation & Contingency
Mitigation: Index user_roles on user_id and org_unit_id. Use JWT claim extraction as the primary fast path; fall back to the RPC only when claims are absent or stale. Set a 3-second timeout with a fallback to cached roles.
Contingency: If RPC latency exceeds acceptable thresholds in production, pre-fetch and embed roles into the session JWT at login time via a Supabase Auth hook, eliminating the post-login RPC entirely.
Users who belong to multiple organizations (e.g., a coordinator in one NHF chapter who is also a peer mentor in another) may have conflicting role assignments. The repository layer must correctly scope roles to the active organization context set during the organization selection step, or it could return roles from the wrong org.
Mitigation & Contingency
Mitigation: Always filter role queries by the active org_unit_id stored in the tenant session. Write integration tests that simulate multi-org users and verify only the correct org's roles are returned.
Contingency: If org-scoping logic is found to be incorrect during QA, add an explicit org_unit_id parameter to get_my_roles RPC and require the client to always pass the active org context, making the scoping explicit rather than inferred.