API Routing & Structure
Relevant source files
The following files were used as context for generating this wiki page:
- backend/src/index.ts
- backend/src/routes/index.ts
- backend/src/modules/users/users.routes.ts
- backend/src/modules/roles/roles.routes.ts
- backend/src/modules/tables/tables.routes.ts
- backend/src/modules/permissions/permissions.routes.ts
- backend/src/modules/me/me.routes.ts
- backend/src/modules/demo/demo.routes.ts
- PLAN.md
Introduction
The MuteTaxes Backend utilizes a modular routing architecture built on Express.js to manage relationship-based access control (ReBAC). The system is designed to provide a clear separation between administrative management (users, roles, tables) and user-centric visualization (personal permissions and allowed resources). All API endpoints are prefixed with /api and integrated with OpenFGA for granular permission checking.
Sources: backend/src/index.ts:1-20, PLAN.md:124-142
System Architecture & Request Flow
The application entry point initializes an Express server, configures global middleware like CORS and JSON parsing, and mounts the central router. The routing logic is decentralized into specific modules, each responsible for a distinct domain of the authorization system.
Core Routing Components
The primary router aggregates several specialized sub-routers:
- Auth/Users: Handles authentication and user management.
- Roles: Manages role definitions.
- Tables: Manages the registry of protected resources.
- Permissions: Provides the administrative matrix for CRUD assignment.
- Me: Provides endpoints for the current user to discover their own access.
- Demo: Contains mocked business logic protected by authorization middleware.
Sources: backend/src/routes/index.ts:1-20, backend/src/index.ts:7-22
Request Lifecycle
The diagram shows the hierarchical flow of a request from the client through global middleware and authentication checks before reaching specific module logic.
Sources: backend/src/index.ts:9-25, backend/src/routes/index.ts:10-18
Module Breakdown
User & Role Management
Administrative modules handle the creation of users and roles, and the mapping between them. These routes typically utilize requireSuperAdmin middleware to restrict access.
| Endpoint | Method | Purpose | Source |
|---|---|---|---|
/api/users | GET | List all users and their assigned roles | users.routes.ts:10-21 |
/api/users/:id/roles | POST | Assign a specific role to a user | users.routes.ts:32-50 |
/api/roles | GET | List all defined roles | roles.routes.ts:11-14 |
/api/roles/:id | DELETE | Remove a role and its FGA tuples | roles.routes.ts:25-50 |
Permission Matrix & OpenFGA Integration
The permissions module provides a "matrix" view, querying OpenFGA to determine which roles have which CRUD "badges" (creator, reader, updater, deleter) on specific tables.
This sequence illustrates how the system aggregates data from both the relational database and the authorization server to build the permission overview.
Sources: backend/src/modules/permissions/permissions.routes.ts:12-41, PLAN.md:78-98
Resource & Visualization Endpoints
The /me module allows users to query their specific permissions without needing administrative privileges. This is used by the frontend to dynamically render sidebars and action buttons.
- GET
/me/allowed-tables: Iterates through all tables and performs acan_readcheck for the authenticated user via OpenFGA. - GET
/me/table-permissions: Returns a detailed CRUD permission set for a specific table slug.
Sources: backend/src/modules/me/me.routes.ts:9-52, PLAN.md:100-116
Middleware & Protection
The routing structure relies heavily on tiered middleware for security:
- authenticate: Validates the JWT and attaches the user object to the request.
- requireSuperAdmin: Restricts access to management endpoints.
- authorizeTable(action, table): A specialized middleware used in the Demo module to verify if a user has the specific FgaAction (create, read, update, delete) on a resource.
Sources: backend/src/modules/demo/demo.routes.ts:8-23, backend/src/modules/users/users.routes.ts:9, backend/src/modules/permissions/permissions.routes.ts:9
Conclusion
The API structure effectively bridges standard RESTful patterns with a Relationship-Based Access Control (ReBAC) model. By separating administrative management from user discovery and resource access, the architecture ensures that OpenFGA remains the source of truth for permissions while maintaining a developer-friendly Express.js routing environment.