Module: User Management
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The User Management module provides the core functionality for managing user identities, their associated roles, and their authorization levels within the MuteTaxes system. It acts as the bridge between persistent identity storage in PostgreSQL and the relationship-based access control (ReBAC) enforcement handled by OpenFGA.
The primary purpose of this module is to allow administrative users (specifically those with the superadmin role) to create new users, view the existing user registry, and modify user-role assignments. This system ensures that every user has a verifiable identity and specific permissions determined by their role memberships, which are synchronized across both the database and the OpenFGA authorization server.
Architecture and Data Flow
User management follows a dual-write architecture. When a user is assigned or removed from a role, the system updates the local PostgreSQL database via Prisma and simultaneously updates the authorization tuples in OpenFGA. This ensures that the primary application database remains the source of truth for metadata, while OpenFGA handles high-performance relationship-based checks.
Entity Relationships
The module utilizes a many-to-many relationship between Users and Roles, managed through a join table (UserRole).
Role Assignment Flow
The assignment of a role to a user involves both a database upsert and an OpenFGA tuple write.
User Management Components
API Endpoints (Admin Only)
Access to user management endpoints is strictly restricted to users possessing the superadmin role through the requireSuperAdmin middleware.
| Method | Endpoint | Description |
|---|---|---|
GET | /users | Retrieves a list of all users, including their assigned roles. |
POST | /users | Creates a new user record in the database. |
POST | /users/:id/roles | Assigns a specific role to a user and syncs the tuple to OpenFGA. |
DELETE | /users/:id/roles/:role | Removes a role from a user and deletes the tuple in OpenFGA. |
Sources: backend/src/modules/users/users.routes.ts:10-67, backend/src/middleware/requireSuperAdmin.ts:7-28
Middleware Enforcement
The requireSuperAdmin middleware performs a lookup against the UserRole table to verify if the requesting user is linked to the superadmin role before allowing access to management routes.
// backend/src/middleware/requireSuperAdmin.ts:16-25
const role = await prisma.role.findUnique({ where: { name: "superadmin" } });
if (!role) {
return res.status(403).json({ error: "Super admin role missing" });
}
const mapping = await prisma.userRole.findUnique({
where: { userId_roleId: { userId: req.user.id, roleId: role.id } }
});
if (!mapping) {
return res.status(403).json({ error: "Forbidden" });
}
Frontend Implementation
The user management interface (located in UsersPage.tsx) provides a dashboard for administrators to perform CRUD operations on users and manage their roles through a reactive UI.
Key Functions
- load(): Fetches the list of users and roles to populate the management table.
- handleCreateUser(): Submits the
POST /usersrequest to add a new user. - handleAssign(): Triggers the role assignment process for a selected user and role name.
- handleRemove(): Removes an existing role from a user.
Sources: frontend/src/pages/UsersPage.tsx:16-60
Admin UI View
The interface presents a list of users, each showing their unique ID and current role badges. Roles can be removed by clicking the "✕" on the badge, provided the role is not superadmin.
Conclusion
The User Management module provides the foundational security layer for the CRM demo. By integrating PostgreSQL for persistence and OpenFGA for relationship-based access, it ensures that user roles are not just static labels but functional components of the authorization engine. This dual-layer approach allows for robust administrative control while maintaining high-performance permission checks throughout the application.