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, and purchase orders
- 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
- admin diagnostics with runtime footprint, record counts, and persisted audit-trail visibility
- admin user management with account creation, activation, role assignment, and role-permission editing
- 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 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](D:/CODING/mrp-codex/CHANGELOG.md)
- [README.md](D:/CODING/mrp-codex/README.md)
- [INSTRUCTIONS.md](D:/CODING/mrp-codex/INSTRUCTIONS.md)
- [STRUCTURE.md](D:/CODING/mrp-codex/STRUCTURE.md)
- [ROADMAP.md](D:/CODING/mrp-codex/ROADMAP.md)
- [UNRAID.md](D:/CODING/mrp-codex/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. Convert demand-planning recommendations into work orders and purchase orders
2. Shared shortage and readiness rollups across planning, purchasing, manufacturing, and projects

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