Data Seeding

Relevant source files

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

• backend/src/seed.ts
• PLAN.md
• backend/prisma/schema.prisma
• backend/src/fga/fgaClient.ts
• backend/package.json
• backend/prisma/migrations/20260122120201_init/migration.sql

Data seeding in the MuteTaxes project is a critical Phase 0 process designed to initialize both the relational database (PostgreSQL) and the Fine-Grained Authorization (FGA) service. The primary purpose is to establish a functional "Super Admin" environment, register core resource types, and deploy the initial authorization model so the system is ready for immediate use after infrastructure setup.

The seeding logic is centralized in the backend and targets two distinct storage layers: the primary database via Prisma ORM and the OpenFGA server via the OpenFGA SDK. This ensures that the identity data in the database remains synchronized with the relationship tuples in the authorization engine.

Sources: PLAN.md:104-121, backend/src/seed.ts:1-12

Seeding Architecture and Flow

The seeding process follows a specific sequence where the relational database is populated first to generate unique identifiers (UUIDs), which are subsequently used to create relationship tuples in OpenFGA.

The diagram above illustrates the dependency flow: OpenFGA seeding requires IDs generated during the Prisma database seeding phase.
Sources: PLAN.md:123-132, backend/src/seed.ts:31-137

Relational Database Initialization

The relational database is seeded using Prisma's upsert operations to ensure idempotency. The seeding script initializes core entities required for the system's management interface.

Initial Entities

The following table describes the data objects created during the initial seed:

Entity	Default Value(s)	Purpose
User	username: "super_admin"	Provides the initial login for system configuration.
Role	name: "superadmin", description: "Super Admin"	The highest privilege role in the system.
Table	clients, companies, invoices, documents, tasks	Standard CRM resource registries for demo purposes.

Sources: backend/src/seed.ts:20-26, backend/src/seed.ts:32-55, PLAN.md:123-130

Database Schema Context

The seeding script targets the schema defined in the project's migrations, ensuring that the UserRole join table correctly links the seeded super_admin to the superadmin role.

Sources: backend/prisma/migrations/20260122120201_init/migration.sql:1-49

OpenFGA Authorization Seeding

The OpenFGA seeding phase is responsible for two main tasks: deploying the Authorization Model and writing initial Relationship Tuples.

Authorization Model Deployment

The script reads the DSL from infra/openfga/model.fga, transforms it into a JSON object using the @openfga/syntax-transformer, and writes it to the OpenFGA server. This defines the types (user, role, table) and relations (member, creator, reader, etc.) used throughout the application.

Sources: backend/src/seed.ts:100-112, backend/src/fga/fgaClient.ts:50-65

Relationship Tuple Seeding

Once the model is active, the system writes "tuples" that define the actual access control logic for the seeded data:

1. Role Membership: Assigns the super_admin user as a member of role:superadmin.
2. Resource Ownership: Grants the superadmin role the creator badge for every seeded table (clients, invoices, etc.).

This structure ensures that the super admin has inherited permissions (defined in the FGA model) to read, update, and delete these tables via the creator relation.
Sources: backend/src/seed.ts:77-92, PLAN.md:131-132

Execution and Tools

The seeding process is integrated into the backend's lifecycle via the package.json scripts. It utilizes ts-node-esm to execute the TypeScript seeding script directly.

Command	Action
npm run seed	Executes ts-node-esm src/seed.ts to trigger the full seeding flow.
npx prisma db seed	Alternative entry point often triggered during migrations.

Sources: backend/package.json:11, PLAN.md:154

Summary

Data seeding provides a "ready-to-go" state for the MuteTaxes backend. By populating PostgreSQL with initial users and tables, and simultaneously configuring OpenFGA with an authorization model and root-level permissions, it bridges the gap between raw infrastructure and a functional, secure application environment. This dual-layer approach ensures that the relationship-based access control (ReBAC) system is fully operational from the first login.

Sources: PLAN.md:104-106, backend/src/seed.ts:139-148