mrp/AGENTS.md

AGENTS.md

Purpose

This file defines project-specific guidance for future contributors and coding agents working in this repository. Follow it alongside the main project docs.

Project overview

MRP Codex is a modular Manufacturing Resource Planning platform intended to be a lighter, sleeker alternative to Odoo. The current repository contains the foundation release:

• React + Vite + Tailwind frontend
• Express + TypeScript backend
• Prisma + SQLite persistence
• local JWT auth and RBAC
• Company Settings and runtime branding
• filesystem-backed attachments
• CRM customers/vendors, hierarchy, contacts, lifecycle metadata, and attachments
• inventory items, BOMs, warehouses, locations, transactions, item attachments, and item pricing
• sales quotes, sales orders, and purchase orders
• shipping shipments and packing-slip PDFs
• Puppeteer PDF foundation
• single-container Docker deployment

Source of truth documents

Read these before major work:

• README.md
• INSTRUCTIONS.md
• STRUCTURE.md
• ROADMAP.md
• UNRAID.md

If implementation changes invalidate those docs, update them in the same change set.

Architecture rules

Keep the app modular by domain

• Backend modules belong under server/src/modules/<domain>
• Frontend modules belong under client/src/modules/<domain>
• Shared contracts belong under shared/src
• Do not collapse unrelated business logic into the app shell or generic utility folders

Backend boundaries

• Keep routers thin
• Put business logic in services
• Put persistence access behind Prisma usage in module services or focused helpers
• Keep auth, RBAC, storage, and Prisma setup in server/src/lib
• Keep environment and path configuration in server/src/config

Frontend boundaries

• Shared UI primitives go in client/src/components
• Theme logic goes in client/src/theme
• Authentication state goes in client/src/auth
• Route-level business pages go in client/src/modules
• Do not mix PDF template concerns into normal UI pages

Shared package constraints

• shared must stay framework-agnostic
• Use explicit .js relative exports/imports in shared/src because it ships as Node ESM
• Keep DTOs, permission keys, and cross-app types there

Data and persistence rules

• SQLite database must live under /app/data/prisma/app.db
• Uploaded files must live under /app/data/uploads
• Never store file blobs in SQLite
• Store metadata and relative paths only
• Any persisted schema change must include a Prisma migration in server/prisma/migrations

Prisma rules

• Run npm run prisma:generate after Prisma schema changes
• Use committed migrations as the source of truth
• Prefer Node 22 or Docker for Prisma migration execution
• Prisma client generation for Docker must continue to support the runtime binary target:
  • debian-openssl-3.0.x
• Do not remove the current binaryTargets setting from server/prisma/schema.prisma unless the base image changes and the runtime target is updated intentionally

Docker rules

• The Dockerfile is designed for command-line builds from the repo root
• Do not reintroduce Puppeteer browser downloads during image build
• The runtime image uses system Chromium at /usr/bin/chromium
• Container startup must continue to apply Prisma migrations before launching the app
• If Docker/runtime dependency handling changes, verify:
  • Prisma binary is present
  • Prisma client is generated in the runtime image
  • shared ESM output resolves correctly in Node

UI and product rules

• The application must remain brandable through centralized theme tokens and Company Settings
• Light and dark mode must remain first-class, not bolted on later
• New UI should respect the theme system and avoid hardcoded one-off colors where possible
• Keep the interface intentional and operational, not generic admin-template filler
• Non-filter operational lookups must use searchable pickers/autocomplete instead of long static dropdowns
• Keep the denser UI baseline on active screens unless a specific workflow needs more space
• Inventory items maintain both cost and price; sales entry should default from item price
• Purchase-order item lookup must only expose inventory items flagged as purchasable
• Customer-facing and logistics PDFs should continue to use the backend documents module and Puppeteer pipeline
• The landing experience should remain Dashboard, not Overview, and should evolve as a modular metric-first operational surface

Feature expectations

Near-term priorities are:

1. Purchase receiving flow and vendor-side operational depth
2. Sales and purchasing PDF templates
3. Shipping labels, bills of lading, and logistics attachments
4. Live manufacturing gantt scheduling
5. Audit and operations maturity

When adding new modules, preserve the ability to extend the system without refactoring the existing app shell.

Testing and verification

Before closing substantial work:

• run npm run build
• run npm run test
• if Docker-related code changed, rebuild the image if the environment allows it
• if Prisma schema changed, regenerate the client and confirm migrations are present

If you cannot run one of those checks, say so explicitly.

Git and workflow expectations

• Keep commits focused and source-only; do not commit generated local build artifacts
• Update roadmap/docs when major work shifts priorities or architecture
• Do not remove or overwrite user changes without explicit instruction
• If a task reveals a persistent operational issue, document it rather than leaving it tribal knowledge

Known pitfalls already encountered

• npx prisma from /app did not resolve correctly in the container; the entrypoint uses the server workspace binary directly
• Prisma client must be generated in the production dependency stage of the Docker build
• Prisma runtime on Debian bookworm requires debian-openssl-3.0.x
• shared package exports must use Node ESM-compatible .js specifiers
• Local Docker validation may fail if the Docker daemon is unavailable; distinguish daemon issues from image issues