Configuration & Environment Variables

Relevant source files

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

• backend/src/config/env.ts
• PLAN.md
• backend/package.json
• backend/src/fga/fgaClient.ts
• backend/src/seed.ts

The MuteTaxes_Backend system relies on a structured configuration management strategy centered around environment variables. This approach ensures that sensitive credentials, infrastructure endpoints, and operational parameters remain decoupled from the application logic. The configuration is primarily managed through standard .env files and a dedicated validation layer in the backend, while the frontend utilizes Vite-specific environment prefixes.

This system is critical for coordinating the relationship between three primary infrastructure components: the Express.js API server, the PostgreSQL database (managed via Prisma), and the OpenFGA authorization server.

Sources: PLAN.md:10-25, backend/src/config/env.ts:1-18

Backend Configuration Architecture

The backend configuration is centralized in backend/src/config/env.ts. It utilizes the dotenv package to load variables from a local environment file into process.env. The system employs a requireEnv helper function to enforce the presence of critical variables during application startup, preventing runtime failures due to missing configuration.

Configuration Validation Flow

The following diagram illustrates how the backend validates environment variables before exposing them to the application modules.

The requireEnv function serves as a gatekeeper, ensuring that the JWT_SECRET, DATABASE_URL, and OPENFGA_API_URL are explicitly defined.

Sources: backend/src/config/env.ts:3-18

Environment Variables Registry

Variable	Type	Description	Required
PORT	Number	The port the Express server listens on (Default: 5050).	No
JWT_SECRET	String	Secret key used for signing and verifying JSON Web Tokens.	Yes
DATABASE_URL	String	Connection string for the PostgreSQL database.	Yes
OPENFGA_API_URL	String	The base URL for the OpenFGA server API.	Yes
OPENFGA_STORE_ID	String	The unique identifier for the OpenFGA store.	No
OPENFGA_AUTH_MODEL_ID	String	The specific authorization model ID to use.	No

Sources: backend/src/config/env.ts:11-18, PLAN.md:235-241

OpenFGA Configuration Logic

The OpenFGA client integration utilizes environment variables to establish a connection and resolve authorization models. The client is initialized using the OPENFGA_API_URL and defaults to CredentialsMethod.None for local demo environments.

Model Resolution Strategy

The system features an automated resolution logic in backend/src/fga/fgaClient.ts that prioritizes environment variables but can fall back to automatic discovery:

1. Direct ID: If OPENFGA_AUTH_MODEL_ID is provided, the system attempts to use it directly after verifying it contains required types (role, table, user).
2. Latest Model: If no ID is provided, it queries the OpenFGA store for the most recent valid model.
3. Bootstrap: If no valid model is found, it reads the local model.fga file, transforms it to JSON, and writes a new model to the server.

Infrastructure & Seeding Configuration

The configuration system also extends to the initialization and seeding of the database and authorization store. The seed.ts file utilizes the same environment variables to ensure consistency between the application state and the infrastructure.

• Database Seeding: Uses DATABASE_URL to create the initial super_admin user and default system tables (clients, invoices, etc.).
• FGA Seeding: Uses OPENFGA_API_URL, OPENFGA_STORE_ID, and OPENFGA_AUTH_MODEL_ID to create the initial authorization tuples for the superadmin role.

Sources: backend/src/seed.ts:10-50, backend/package.json:8-13

Frontend Configuration

The frontend, built with Vite, uses a specific environment variable for API communication. This is typically stored in a .env file at the root of the frontend directory.

Variable	Description
VITE_API_BASE_URL	The URL of the backend API (e.g., http://localhost:5050/api).

Sources: PLAN.md:244-246, frontend/package.json:6-10

Summary

The MuteTaxes_Backend configuration system provides a robust foundation for multi-environment deployment. By centralizing variable validation in the backend and utilizing OpenFGA environment variables for dynamic model resolution, the architecture maintains security while allowing for automated infrastructure bootstrapping. This setup ensures that developers only need to manage a standard set of environment keys to fully configure the database, authentication, and authorization layers.