diff --git a/ROADMAP.md b/ROADMAP.md new file mode 100644 index 0000000..65cd0bd --- /dev/null +++ b/ROADMAP.md @@ -0,0 +1,99 @@ +# Roadmap + +## Product direction + +MRP Codex is being built as a streamlined, modular manufacturing resource planning platform with strong branding controls, fast operational workflows, and a single-container deployment model that is simple to back up and upgrade. + +## Current status + +### Completed: Foundation release + +- Monorepo-style workspace with `client`, `server`, and `shared` +- React + Vite + Tailwind frontend shell +- Express + TypeScript backend shell +- Prisma + SQLite schema foundation with committed initial migration +- Local authentication with JWT-based session flow +- RBAC permission model and protected routes +- Central Company Settings with runtime branding controls +- Light and dark mode theme system +- Local file attachment storage under `/app/data/uploads` +- Puppeteer PDF service foundation with branded company-profile preview +- CRM reference entities for customers and vendors +- SVAR Gantt integration wrapper with demo planning data +- Multi-stage Docker packaging and migration-aware entrypoint +- Core project documentation in `README.md`, `INSTRUCTIONS.md`, and `STRUCTURE.md` + +### Current known gaps in the foundation + +- Docker runtime has been authored but not validated in this environment because the local Docker daemon was unavailable +- Prisma migration execution is committed and documented, but local Windows Node 24 schema-engine behavior remains inconsistent; use Node 22 or Docker for migration execution +- The frontend bundle is functional but should be code-split later, especially around the gantt module +- CRM is currently read-focused and seeded; create/update/detail workflows still need to be built + +## Planned feature phases + +### Phase 1: CRM and master data hardening + +- Customer and vendor create/edit/detail pages +- Search, filters, and status tagging +- Contact history and internal notes +- Shared attachment support on CRM entities +- Better seed/bootstrap strategy for non-development environments + +### Phase 2: Inventory and manufacturing core + +- Item master and SKU structure +- Warehouse and stock location modeling +- Inventory transactions and on-hand tracking +- Bills of materials and custom assemblies +- Project records tied to manufacturing work +- File attachments for BOM drawings and manufacturing support docs + +### Phase 3: Sales and purchasing documents + +- Quotes, sales orders, and purchase orders +- Reusable line-item and totals model +- Document states, approvals, and revision history +- Branded PDF templates rendered through Puppeteer +- Attachments for vendor invoices and supporting documents + +### Phase 4: Shipping and logistics + +- Shipment records linked to sales orders +- Bills of lading, packing slips, and shipping BOM PDFs +- Carrier, package, and tracking data +- Outbound shipment status workflow +- Scanned logistics-document attachment handling + +### Phase 5: Manufacturing planning and scheduling + +- Live project-backed SVAR gantt timelines +- Task dependencies, milestones, and progress updates +- Manufacturing calendar views and bottleneck visibility +- Labor and machine scheduling support +- Theme-compliant gantt customization for light/dark mode + +### Phase 6: Security, audit, and operations maturity + +- Expanded role management UI +- Permission assignment administration +- Audit trail coverage across critical records +- Backup/restore workflow documentation and scripts +- Health checks, startup diagnostics, and production readiness cleanup + +## Cross-cutting improvements + +- Stronger validation and error reporting across all APIs +- More automated tests for auth, settings, files, PDFs, and workflow modules +- Better mobile behavior in module-level pages +- Consistent document-template system shared by sales, purchasing, and shipping +- Clear upgrade path for future module additions without refactoring the app shell + +## Near-term priority order + +1. CRM detail and edit workflows +2. Inventory item and BOM data model +3. Sales order and quote foundation +4. Shipping module tied to sales orders +5. Live manufacturing gantt scheduling + diff --git a/UNRAID.md b/UNRAID.md new file mode 100644 index 0000000..c345405 --- /dev/null +++ b/UNRAID.md @@ -0,0 +1,188 @@ +# Unraid Install Guide + +## Purpose + +This guide explains how to deploy MRP Codex on an Unraid server using the Unraid Docker GUI rather than command-line Docker management. + +## What this container expects + +- One published web port for the application +- One persistent app data path mounted to `/app/data` +- Environment variables for the server port, JWT secret, and SQLite path +- Automatic Prisma migration execution during container startup + +MRP Codex stores both the SQLite database and uploaded files inside the same persistent container path: + +- database: `/app/data/prisma/app.db` +- uploads: `/app/data/uploads` + +## Before you start + +- Build and push the image to a registry your Unraid server can access, or import it manually if you are self-hosting images +- Choose an Unraid share for persistent app data, for example: + - `/mnt/user/appdata/mrp-codex` +- Choose the port you want to expose in Unraid, for example: + - host port `3000` + - container port `3000` + +## Recommended Unraid paths + +- App data share: `/mnt/user/appdata/mrp-codex` +- Optional backup target: `/mnt/user/backups/mrp-codex` + +Keep the entire app data folder together so backups capture both the SQLite database and file attachments. + +## Add the container in the Unraid GUI + +### 1. Open the Docker tab + +- In Unraid, go to `Docker` +- Click `Add Container` + +### 2. Basic container settings + +Use these values as the starting point: + +- Name: `mrp-codex` +- Repository: your built image name, for example `your-registry/mrp-codex:latest` +- Network Type: `bridge` +- Console shell command: leave default +- Privileged: `Off` + +### 3. Port mapping + +Add a port mapping: + +- Name: `WebUI` +- Container Port: `3000` +- Host Port: `3000` +- Connection Type: `TCP` + +If port `3000` is already used on the Unraid host, change only the host port. + +### 4. Path mapping + +Add a single path mapping: + +- Name: `data` +- Container Path: `/app/data` +- Host Path: `/mnt/user/appdata/mrp-codex` +- Access Mode: `Read/Write` + +This is the critical mapping. Do not split the database and uploads into separate container paths unless you also update the app configuration. + +### 5. Environment variables + +Add these variables in the Unraid GUI: + +- `NODE_ENV` = `production` +- `PORT` = `3000` +- `JWT_SECRET` = `replace-with-a-long-random-secret` +- `DATA_DIR` = `/app/data` +- `DATABASE_URL` = `file:../../data/prisma/app.db` +- `PUPPETEER_EXECUTABLE_PATH` = `/usr/bin/chromium` +- `CLIENT_ORIGIN` = `http://YOUR-UNRAID-IP:3000` + +If you use a reverse proxy and external hostname, set `CLIENT_ORIGIN` to the final browser URL instead, for example: + +- `CLIENT_ORIGIN` = `https://mrp.yourdomain.com` + +### 6. Optional first-admin overrides + +You can set the seeded admin login explicitly on first deployment: + +- `ADMIN_EMAIL` = `admin@yourcompany.com` +- `ADMIN_PASSWORD` = `use-a-strong-initial-password` + +If you do not set them, the defaults from the app bootstrapping logic are used. + +## First start behavior + +On first container start, the entrypoint will: + +1. Ensure `/app/data/prisma` and `/app/data/uploads` exist +2. Run `npx prisma migrate deploy` +3. Start the Node.js server + +The frontend is served by the same container as the API, so there is only one exposed web port. + +## First login + +If you did not override the admin credentials with environment variables, use: + +- email: `admin@mrp.local` +- password: `ChangeMe123!` + +Change the admin password after first login if you keep the default bootstrap user. + +## Updating the container in Unraid + +When you publish a new image: + +1. Open the `Docker` tab +2. Apply the update from the Unraid GUI +3. Start the container + +Because MRP Codex runs `prisma migrate deploy` during startup, committed migrations are applied automatically before the app launches. + +## Backup guidance + +Back up the host directory mapped to `/app/data`, typically: + +- `/mnt/user/appdata/mrp-codex` + +That captures: + +- the SQLite database +- uploaded CAD drawings and supporting files +- logos and other persisted attachments + +For consistent backups, stop the container before copying the appdata directory. + +## Reverse proxy notes + +If you place MRP Codex behind Nginx Proxy Manager, Traefik, or another reverse proxy: + +- keep the Unraid container on `bridge` or your preferred proxy-compatible network +- point the proxy at the Unraid host IP and chosen host port +- set `CLIENT_ORIGIN` to the final external URL + +## Troubleshooting + +### Container starts then exits + +Check the container logs in Unraid. Common causes: + +- invalid `DATABASE_URL` +- missing write access to the host path mapped to `/app/data` +- bad or missing environment values + +### PDFs fail to generate + +The image already includes Chromium and the required runtime libraries. If PDF generation still fails: + +- confirm `PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium` +- inspect the container logs for Puppeteer launch errors + +### Application boots but data does not persist + +Verify the `/app/data` path mapping in Unraid. If `/app/data` is not mapped to a persistent Unraid share, the database and uploads will be lost when the container is recreated. + +### Browser login or CORS issues + +Set `CLIENT_ORIGIN` to the exact URL used by the browser, including protocol and port. + +## Suggested Unraid template summary + +- Repository: `your-registry/mrp-codex:latest` +- Network Type: `bridge` +- Port: `3000` -> `3000` +- Path: `/mnt/user/appdata/mrp-codex` -> `/app/data` +- Env: `NODE_ENV=production` +- Env: `PORT=3000` +- Env: `JWT_SECRET=` +- Env: `DATA_DIR=/app/data` +- Env: `DATABASE_URL=file:../../data/prisma/app.db` +- Env: `PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium` +- Env: `CLIENT_ORIGIN=http://YOUR-UNRAID-IP:3000` +