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, packing-slip PDFs, shipping labels, bills of lading, and logistics attachments
- projects with customer/commercial/shipment linkage, owners, due dates, notes, and attachments
- 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 should remain a separate future domain for work orders, routings, labor, and shop-floor execution
- 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. Manufacturing execution
2. Vendor invoice/supporting-document attachments and broader vendor-side operational depth
3. Sales approvals and document revision history
4. Planning and gantt scheduling with live project/manufacturing data
5. Inventory transfers, reservations, and deeper stock controls

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