Production Deployment

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/fga/fgaClient.ts
• backend/src/seed.ts

The production deployment of the MuteTaxes system involves a containerized microservices architecture composed of a Node.js TypeScript backend, a Vite-based React frontend, and supporting infrastructure including PostgreSQL and an OpenFGA authorization server. The system is designed to provide relationship-based access control (ReBAC) by decoupling authorization logic from the core application database.

The deployment strategy focuses on ensuring that the OpenFGA authorization model is correctly applied and that all environment-specific configurations for the database and authorization store are properly initialized. This includes running database migrations via Prisma and seeding initial super-admin credentials and relationship tuples.

Sources: PLAN.md:8-15, PLAN.md:104-124

System Architecture

The deployment architecture consists of four primary components managed via Docker Compose. The backend acts as the orchestrator, communicating with PostgreSQL for relational data and OpenFGA for authorization checks.

Infrastructure Components

The infrastructure is defined through a multi-container setup. Key dependencies for a successful deployment include:

Component	Technology	Role
Backend	Node.js (TypeScript)	Serves the REST API and handles business logic.
Frontend	React (Vite)	Provides the administrative and user interface.
Database	PostgreSQL	Stores Users, Roles, and Table metadata.
Auth Engine	OpenFGA	Evaluates relationship-based access tuples.

Sources: PLAN.md:14-23, backend/package.json:15-25

Backend Deployment and Lifecycle

The backend service requires a build phase to transpile TypeScript into JavaScript. In production, the service is executed using the node runtime rather than development tools like ts-node-dev.

Build and Run Commands

The following scripts define the deployment lifecycle:

• Build: npm run build (runs tsc -p tsconfig.json)
• Start: node dist/index.js
• Migration: prisma migrate dev (used to sync the PostgreSQL schema)

Sources: backend/package.json:6-12

Environment Configuration

The backend requires several environment variables to connect to infrastructure and secure the API:

Variable	Description
DATABASE_URL	PostgreSQL connection string.
JWT_SECRET	Secret key for signing authentication tokens.
OPENFGA_API_URL	Endpoint for the OpenFGA server.
OPENFGA_STORE_ID	The specific store ID within OpenFGA.
OPENFGA_AUTH_MODEL_ID	The ID of the compiled authorization model.

Sources: PLAN.md:213-219

Authorization Model Initialization

A critical step in production deployment is the "Ensure Model" logic. Upon startup, the backend checks if a valid OpenFGA authorization model exists. If not, it reads the DSL from infra/openfga/model.fga, transforms it into a JSON object, and writes it to the OpenFGA server.

Database Seeding and Migration

Before the system is usable, it must be seeded with initial data. The seed.ts script performs two primary functions:

1. Relational Seeding: Creates the super_admin user and superadmin role in PostgreSQL. It also populates the Table registry (e.g., clients, invoices).
2. Tuple Seeding: Writes initial relationship tuples to OpenFGA, specifically assigning the super_admin user as a member of the superadmin role and granting that role creator permissions on all tables.

Sources: backend/src/seed.ts:21-65

Frontend Deployment

The frontend is a static single-page application (SPA). During deployment, it must be built into optimized assets.

• Dependencies: React 18 and React Router DOM.
• Build Process: npm run build executes tsc -b followed by vite build.
• Environment: The VITE_API_BASE_URL must point to the production backend API.

Sources: frontend/package.json:6-14, PLAN.md:223-225

Summary of Deployment Steps

1. Infrastructure: Start PostgreSQL and OpenFGA via Docker.
2. Database: Run Prisma migrations to set up the schema in PostgreSQL.
3. Authorization: The backend initializes the OpenFGA store and uploads the FGA model if it doesn't exist.
4. Seeding: Execute the seed script to create the initial administrative user and global permissions.
5. Frontend: Build the React application and host it via a web server (e.g., Nginx) or the Vite preview.

Sources: PLAN.md:126-147, backend/src/fga/fgaClient.ts:55-80