Getting Started & Local Setup

Relevant source files

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

• PLAN.md
• backend/package.json
• frontend/package.json
• backend/src/index.ts
• backend/src/seed.ts
• backend/src/fga/fgaClient.ts

The MuteTaxes CRM Demo is a prototype designed to visualize relationship-based authorization using OpenFGA and PostgreSQL. The system focuses on how roles and permissions are defined via relationship tuples and how the user interface dynamically adapts based on these live permission checks.

The local setup involves orchestrating a multi-tier architecture consisting of a Node.js Express backend, a Vite-based React frontend, and infrastructure services including PostgreSQL and an OpenFGA server managed via Docker Compose.

Sources: PLAN.md:1-12, PLAN.md:20-27

Architecture Overview

The project is structured into three primary directories: /backend, /frontend, and /infra. The backend serves as the API layer and OpenFGA integrator, while the frontend provides the administrative and user-facing interfaces.

System Components

Component	Technology	Role
Backend	Node.js, Express, TypeScript	API logic and OpenFGA client integration.
Frontend	React, Vite, TailwindCSS	Dynamic UI rendering based on authorization.
Database	PostgreSQL	Persistent storage for users, roles, and table metadata.
AuthZ	OpenFGA	Relationship-based access control (ReBAC) engine.
ORM	Prisma	Database modeling and migrations.

Sources: PLAN.md:14-25, backend/package.json:20-30, frontend/package.json:11-20

Component Interaction Flow

The following diagram illustrates how the frontend interacts with the backend and how the backend coordinates between the relational database and the OpenFGA authorization server.

The diagram shows the request flow from the user through the application stack to the data and authorization providers.

Sources: PLAN.md:14-27, backend/src/index.ts:1-25

Infrastructure Setup

The infrastructure is managed through Docker Compose, which initializes the core services required for the application to function.

Docker Services

1. PostgreSQL: Stores application data like users, roles, and table definitions.
2. OpenFGA: Handles authorization checks and relationship tuple storage.

To start the infrastructure:

cd infra
docker compose up -d

Sources: PLAN.md:23-27, PLAN.md:142-145

Backend Configuration

The backend requires several environment variables to communicate with the database and the OpenFGA server. These must be defined in a .env file within the backend/ directory.

Environment Variables

Variable	Description
DATABASE_URL	Connection string for PostgreSQL.
JWT_SECRET	Secret key for signing JSON Web Tokens.
OPENFGA_API_URL	URL of the OpenFGA server (default: http://localhost:8080).
OPENFGA_STORE_ID	The specific store ID within OpenFGA.
OPENFGA_AUTH_MODEL_ID	The ID of the compiled authorization model.

Sources: PLAN.md:223-230, backend/src/fga/fgaClient.ts:40-60

Initialization Steps

1. Install Dependencies: npm install
2. Prisma Migrations: npx prisma migrate dev to sync the database schema.
3. Seeding: npm run seed to create the initial super_admin user and default tables.

Sources: PLAN.md:151-155, backend/package.json:7-12

Data Seeding and OpenFGA Model

The seeding process (backend/src/seed.ts) is critical for the initial setup. It creates the necessary records in PostgreSQL and initializes the OpenFGA store and model.

Seeding Logic Flow

The seeding script ensures that the super_admin user has member status in the superadmin role and that the role has creator badges for all default tables.

Sources: backend/src/seed.ts:32-100, PLAN.md:118-132

Frontend Setup

The frontend is a Vite project that connects to the backend API.

1. Environment Setup: Create a .env file in the frontend/ directory.

   VITE_API_BASE_URL=http://localhost:5050/api
   

2. Install Dependencies: npm install
3. Run Development Server: npm run dev

Sources: PLAN.md:157-160, PLAN.md:235-237, frontend/package.json:7-10

Verification of Setup

Once all components are running, the local environment can be verified through the following steps:

1. Health Check: Access http://localhost:[PORT]/health to verify the backend is responsive.
2. Login: Access the frontend and log in using the username super_admin.
3. API Documentation: Browse http://localhost:[PORT]/docs for the Swagger/OpenAPI documentation.

Sources: backend/src/index.ts:13-17, frontend/src/pages/LoginPage.tsx:40-50, PLAN.md:89-93

The system is now ready for local development, allowing for the creation of new roles, users, and the management of relationship-based permissions via the Permission Matrix.

Sources: PLAN.md:4-8, PLAN.md:183-195