High-Level Architecture

Relevant source files

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

• PLAN.md
• backend/src/index.ts
• backend/src/fga/fgaClient.ts
• backend/src/modules/permissions/permissions.routes.ts
• backend/src/seed.ts
• frontend/src/App.tsx
• frontend/src/api/endpoints.ts

The MuteTaxes project is a relationship-based access control (ReBAC) demonstration platform. It integrates a React-based frontend with a Node.js backend to visualize how permissions are defined via OpenFGA and stored within a PostgreSQL database. The core objective is to showcase dynamic UI adaptation based on live authorization checks, where sidebar visibility and action button states change according to the user's relationship to various resources.

Sources: PLAN.md:3-10, PLAN.md:14-23

System Components

The architecture consists of three primary tiers: the Client Interface, the Application Server, and the Infrastructure services.

Core Architecture Layers

Layer	Technology	Description
Frontend	React, Vite, TailwindCSS	Provides the user interface for managing users, roles, and viewing protected table data.
Backend	Node.js, Express, TypeScript	Handles business logic, JWT authentication, and coordinates between the database and the authorization engine.
Persistence	PostgreSQL, Prisma ORM	Stores application state, including user records, role definitions, and resource metadata.
Authorization	OpenFGA	Serves as the source of truth for relationship-based permissions using a Fine-Grained Authorization model.

Sources: PLAN.md:14-23, backend/package.json:17-25, frontend/package.json:13-16

System Interaction Diagram

The following diagram illustrates the request flow between the user interface, the application server, and the external authorization service.

Authorization Model

The system utilizes OpenFGA to manage relationships. The model defines types for user, role, and table. Permissions are derived from membership in roles and specific "badges" (creator, reader, updater, deleter) assigned to those roles.

OpenFGA Relationship Definitions

The model defines the following core logic for access:

• Member: A user can be a member of a role.
• Badges: Roles are assigned badges on specific tables (e.g., table:clients#reader@role:accountant#member).
• Computed Relations: Permissions like can_read are computed based on whether a user has any of the CRUD badges.

Data Management

Database Schema (Prisma)

The application maintains structural data in PostgreSQL while delegating permission logic to OpenFGA. Key entities include:

• User: Basic authentication details.
• Role: Named groupings for permissions.
• UserRole: A many-to-many link between users and roles.
• Table: A registry of resources (e.g., clients, invoices) that are protected by authorization logic.

Sources: PLAN.md:52-75, backend/src/modules/roles/roles.routes.ts:12-25

Seeding Process

Upon initialization, the system seeds both the database and OpenFGA. It creates a super_admin user, assigns them the superadmin role, and grants that role creator status across all default tables in the OpenFGA store.

Sources: backend/src/seed.ts:31-60, backend/src/seed.ts:80-95

Backend API Structure

The backend is organized into functional modules, each handling a specific domain of the CRM and its associated authorization.

API Routing and Middleware

All API requests flow through a standard pipeline:

1. CORS/JSON Parsing: Basic request handling.
2. Authentication: authenticate middleware validates the JWT and attaches the user to the request.
3. Authorization: requireSuperAdmin or authorizeTable middleware ensures the user has sufficient rights via FGA checks.

Permission Management Endpoints

Endpoint	Method	Description
/api/permissions/matrix	GET	Returns a full grid of roles vs. tables and their current CRUD status.
/api/permissions/up	POST	Updates specific tuples in OpenFGA (writes or deletes badges).
/api/me/table-permissions	GET	Returns the specific permissions for the current user on a single table.

Sources: backend/src/modules/permissions/permissions.routes.ts:12-30, backend/src/modules/permissions/permissions.routes.ts:91-125, frontend/src/api/endpoints.ts:122-126

Frontend Implementation

The frontend is a Single Page Application (SPA) that uses React Router for navigation and a Context API for global state management.

Dynamic UI Rendering

The UI adapts based on the response from the backend's authorization checks:

• Sidebar: Calls /me/allowed-tables to only display links to tables where the user has can_read permissions.
• Action Buttons: Within a specific table view, the frontend checks canCreate, canUpdate, and canDelete flags to enable or disable interaction elements.

Sources: frontend/src/App.tsx:38-75, frontend/src/api/endpoints.ts:119-126, PLAN.md:195-205

Page Routing Architecture

The application distinguishes between standard user routes and protected admin routes:

• RequireAuth: Ensures a valid token exists before rendering the Layout.
• SuperAdminRoute: Specifically guards paths like /users, /roles, and /permissions.

Sources: frontend/src/App.tsx:12-28

Summary

The MuteTaxes architecture demonstrates a clean separation between application data and authorization logic. By offloading complex relationship traversal to OpenFGA, the backend remains stateless regarding permission rules, performing real-time checks to determine access. This setup allows for a highly responsive UI that accurately reflects a user's current permissions across various resources and roles.