Module: Role Management
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Role Management module is a core component of the MuteTaxes system, responsible for defining, assigning, and maintaining administrative and functional roles. It facilitates relationship-based authorization by bridging the gap between the PostgreSQL database (managed via Prisma) and the OpenFGA authorization engine.
This module allows Super Admins to create new roles, delete existing ones, and manage the mapping between users and roles. These mappings are synchronized as tuples in OpenFGA, enabling fine-grained permission checks across the application.
Sources: PLAN.md:3-10, backend/src/modules/roles/roles.routes.ts:1-10
Architecture and Data Flow
The module operates through a dual-persistence strategy. When a role is created or a user is assigned to a role, the system updates both the primary relational database and the OpenFGA store.
Data Schema
The underlying PostgreSQL schema defines the structure for roles and their associations with users.
| Field | Type | Description |
|---|---|---|
id | TEXT (PK) | Unique identifier for the role. |
name | TEXT (Unique) | Unique name of the role (e.g., "superadmin", "accountant"). |
description | TEXT (Optional) | Brief explanation of the role's purpose. |
createdAt | TIMESTAMP | Record creation timestamp. |
Sources: backend/prisma/migrations/20260122120201_init/migration.sql:11-18, PLAN.md:65-71
Role Assignment Flow
The following diagram illustrates the process of assigning a role to a user, involving both the database and OpenFGA.
Component Breakdown
Backend Controllers and Routes
The backend exposes specific endpoints for role operations, restricted to users with the superadmin role through middleware.
- GET
/roles: Retrieves all roles from the database. - POST
/roles: Creates a new role record. - DELETE
/roles/:id: Performs a cascading deletion. It removes the role from the database, deletes all associatedUserRolemappings, and revokes all corresponding permission tuples in OpenFGA.
Sources: backend/src/modules/roles/roles.routes.ts:12-51, backend/src/middleware/requireSuperAdmin.ts:7-29
OpenFGA Integration
The fgaClient serves as the integration layer. It translates application-level role assignments into OpenFGA tuples using the following format:
- User to Role:
user:<userId>#member@role:<roleName> - Role to Resource:
table:<tableSlug>#<badge>@role:<roleName>#member
Frontend Interface
The frontend provides a management dashboard for role administration.
- RolesPage: Provides a form to create roles and a list to view/delete them. The "superadmin" role is protected from deletion via UI logic.
- UsersPage: Allows admins to select a user and assign available roles from a dropdown, or remove existing assignments.
Sources: frontend/src/pages/RolesPage.tsx:45-65, frontend/src/pages/UsersPage.tsx:78-115
Key Implementation Details
User-Role Mapping
The UserRole table facilitates a many-to-many relationship between users and roles.
// backend/src/modules/users/users.routes.ts:46-50
await prisma.userRole.upsert({
where: { userId_roleId: { userId: id, roleId: roleRecord.id } },
update: {},
create: { userId: id, roleId: roleRecord.id }
});
Sources: backend/src/modules/users/users.routes.ts:46-50, backend/prisma/migrations/20260122120201_init/migration.sql:22-27
Role-Based Access Control (RBAC)
The requireSuperAdmin middleware ensures that only users assigned the superadmin role can access role management features. It checks the database for a valid UserRole mapping against the role named "superadmin".
Sources: backend/src/middleware/requireSuperAdmin.ts:15-28
Conclusion
The Role Management module provides the administrative foundation for the application's security model. By synchronizing relational data with OpenFGA, it ensures that role changes are immediately reflected in the relationship-based access control (ReBAC) logic, maintaining a consistent and secure environment for CRM operations.