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
• inventory transfers, reservations, available-stock visibility, and work-order reservation automation
• sales quotes, sales orders, approvals, revision history/comparison, and purchase orders
• purchase-order revision history and revision comparison across document and receipt changes
• purchase-order supporting documents and vendor-side purchasing visibility
• shipping shipments, packing-slip PDFs, shipping labels, bills of lading, and logistics attachments
• projects with customer/commercial/shipment linkage, owners, due dates, notes, and attachments
• manufacturing work orders with project linkage, station master data, item operation templates, auto-generated work-order operations, and attachments
• planning gantt timelines backed by live project and manufacturing schedule data
• sales-order demand planning with multi-level BOM explosion, stock/open-supply netting, and build/buy recommendations
• planner-assisted conversion of demand-planning recommendations into prefilled work-order and purchase-order drafts
• pegged work-order and purchase-order supply coverage tied back to sales demand, with preferred-vendor sourcing defaults
• shared shortage and readiness rollups across dashboard, planning, projects, purchasing, and manufacturing
• admin diagnostics with runtime footprint, record counts, and persisted audit-trail visibility
• admin user management with account creation, activation, role assignment, role-permission editing, session visibility/revocation, and review filtering
• safer destructive-action confirmations and recovery messaging across admin, sales, purchasing, shipping, inventory, manufacturing, projects, warehouse/form editors, and attachment workflows
• CRM/shipping audit coverage and startup validation surfaced through the admin diagnostics workflow
• backup/restore guidance, richer startup diagnostics, and exportable support bundles in the admin diagnostics workflow
• backup verification checklist and restore-drill runbook in the admin diagnostics workflow
• support-log viewing, filtering, retention cleanup, and support debugging helpers in the admin diagnostics workflow
• Puppeteer PDF foundation
• single-container Docker deployment

Source of truth documents

Read these before major work:

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

If implementation changes invalidate those docs, update them in the same change set. Keep CHANGELOG.md current for shipped features, behavior changes, and notable operational updates.

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
• Projects are a first-class domain that anchors long-running program execution across CRM, sales, inventory, purchasing, shipping, and planning, and future work should continue extending that module rather than scattering project state elsewhere
• Manufacturing is now a first-class domain for work orders and inventory-backed execution, and future work should keep expanding it as a separate subsystem for routings, labor, and shop-floor control
• Planning should remain the scheduling/visibility layer over projects and manufacturing, not a replacement for either
• New top-level modules added to shell navigation should ship with a matching SVG icon, not text-only nav entries

Feature expectations

Near-term priorities are:

1. Project milestones and project-side rollup visibility
2. Manufacturing routing/work-center depth, labor capture, and capacity-aware execution views

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 and CHANGELOG.md when major work shifts priorities, architecture, or shipped functionality
• 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