agent

AGENTS.md

@@ -0,0 +1,135 @@
+# 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
+- 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
+
+## Feature expectations
+
+Near-term priorities are:
+
+1. CRM detail and edit workflows
+2. Inventory and BOM data model
+3. Sales and quote foundation
+4. Shipping tied to sales orders
+5. Live manufacturing gantt scheduling
+
+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
+