Adding New Modules

Relevant source files

The following files were used as context for generating this wiki page:

• backend/src/routes/index.ts
• backend/src/modules/demo/demo.routes.ts
• backend/src/modules/tables/tables.routes.ts
• backend/src/modules/users/users.routes.ts
• backend/src/fga/fgaClient.ts
• PLAN.md

Introduction

Adding new modules to the MuteTaxes Backend involves a structured process of defining Express routes, implementing business logic, and integrating with the OpenFGA authorization system. The project architecture follows a modular pattern where each functional area (e.g., users, roles, tables) is encapsulated within its own directory under backend/src/modules.

The scope of adding a module includes registering the resource in the database, defining its API surface, and ensuring that access is controlled via relationship-based authorization tuples. This ensures that permissions remain granular and consistent across the platform.

Sources: PLAN.md:120-131, backend/src/routes/index.ts:1-17

Backend Module Structure

New modules should be placed in backend/src/modules/<module_name>/. A standard module typically contains a routes file that defines the API endpoints and connects them to middleware for authentication and authorization.

Route Registration

All new module routers must be imported and mounted in the central router file to be accessible under the /api prefix.

// backend/src/routes/index.ts
import { Router } from "express";
import { newModuleRoutes } from "../modules/newModule/newModule.routes.js";

export const routes = Router();
routes.use("/new-module", newModuleRoutes);

Sources: backend/src/routes/index.ts:1-17

Component Interaction Flow

The following diagram illustrates how a request flows through a newly added module, specifically highlighting the integration with the Authorization layer.

The flow ensures that any request reaching the module logic has been validated against both identity (Authentication) and relationship-based permissions (Authorization).
Sources: backend/src/modules/demo/demo.routes.ts:5-23, PLAN.md:133-146

Implementing Authorization

When adding a module that manages a new resource (referred to as a "Table" in this system), you must ensure it is registered in the OpenFGA model.

Permission Checks

Modules use the authorizeTable middleware or the checkPermission function from the FGA client to enforce CRUD rules.

Action	Relation Mapping	Description
read	can_read	Allows fetching resource data
create	can_create	Allows creating new resource instances
update	can_update	Allows modifying existing resources
delete	can_delete	Allows removing resources

Sources: backend/src/fga/fgaClient.ts:101-115, backend/src/modules/demo/demo.routes.ts:9-23

FGA Tuple Management

When resources are created or roles are assigned within a module, the system must write tuples to OpenFGA to keep the authorization state in sync.

Module Configuration Checklist

To successfully integrate a new module, the following elements must be implemented:

1. Database Schema: Update prisma/schema.prisma if the module requires new entities.
2. FGA Model: Ensure the resource type exists in infra/openfga/model.fga.
3. Routes: Create <module>.routes.ts using Express Router.
4. Middleware: Apply authenticate and authorizeTable(action, resource) as needed.
5. Global Router: Add the new routes to backend/src/routes/index.ts.

Sources: PLAN.md:104-118, backend/src/modules/tables/tables.routes.ts:1-24

Summary

Adding new modules follows a strict pattern of modularity and "security by design." By leveraging centralized route registration and a robust OpenFGA wrapper, developers can ensure that new features are automatically compatible with the existing authorization matrix and UI visualization logic.

Sources: PLAN.md:204-222, backend/src/routes/index.ts