# 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 and sales 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](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.

## 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
- 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 orders and vendor-side flow
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