From 8505d4fd57016e2789879c209b072d651f2a02b1 Mon Sep 17 00:00:00 2001 From: jason Date: Sat, 14 Mar 2026 15:42:32 -0500 Subject: [PATCH] agent --- AGENTS.md | 135 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 135 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..7b9dbcf --- /dev/null +++ b/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/` +- Frontend modules belong under `client/src/modules/` +- 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 +