CODEXIUM

Foundation release for a modular Manufacturing Resource Planning platform built with React, Express, Prisma, SQLite, and a single-container Docker deployment.

Documentation Maintenance

• Keep CHANGELOG.md updated for shipped features, workflow changes, and notable operational updates.
• Keep README.md, INSTRUCTIONS.md, STRUCTURE.md, ROADMAP.md, SHIPPED.md, and UNRAID.md aligned when changes affect their scope.

Current foundation scope includes:

• authentication and RBAC
• company branding and theme settings, including startup brand-theme hydration across refresh
• CRM customers and vendors with create/edit/detail workflows
• CRM search, filtering, status tagging, and reseller hierarchy
• CRM contact history, account contacts, and shared attachments
• inventory item master, BOM, warehouse, stock-location, and stock-transaction flows
• inventory transfers, reservations, and available-stock visibility
• inventory SKU master builder with family-scoped sequence generation and branch-aware taxonomy management
• staged thumbnail image attachment on inventory item create/edit workflows, with detail-page thumbnail display
• sales quotes and sales orders with searchable customer and SKU entry
• sales approvals, approval stamps, automatic revision history, and revision comparison on quotes and sales orders
• purchase orders with searchable vendor and SKU entry, restricted to purchasable inventory items
• purchase-order revision history and revision comparison across commercial and receipt changes
• purchase receiving with warehouse/location posting and receipt history against purchase orders
• branded quote, sales-order, and purchase-order PDFs through the shared backend document pipeline
• purchase-order supporting documents for vendor invoices, acknowledgements, certifications, and backup files
• shipping shipments linked to sales orders with packing slips, shipping labels, bills of lading, and logistics attachments
• projects with customer/commercial/shipment linkage, owners, due dates, milestones, rollups, notes, and attachments
• manufacturing work orders with project linkage, station-based operation templates, editable station calendars/capacity settings, calendar-aware operation scheduling, operation execution controls, labor posting, material issue posting, completion posting, operation rescheduling, and work-order attachments
• planning workbench with live project/manufacturing schedule data, exception rail, heatmap load view, agenda view, focus drawer, station load grouping, readiness filters, overload visibility, inline dispatch actions, planner-side operation rebalance controls including station-to-station moves, and station-lane drag scheduling
• sales-order demand planning with multi-level BOM explosion, stock/open-supply netting, and build/buy recommendations
• planner-assisted conversion of demand-planning recommendations into prefilled work-order and purchase-order drafts
• pegged WO/PO supply tracking back to sales demand with preferred-vendor sourcing on inventory items
• shared shortage and readiness rollups across dashboard, planning, projects, purchasing, and manufacturing
• admin diagnostics with runtime footprint, record counts, and recent audit-trail visibility
• admin user management with account creation, activation, role assignment, role-permission editing, session visibility/revocation, review filtering, and unusual-access cues
• safer destructive-action confirmations and recovery messaging across admin, sales, purchasing, shipping, inventory, manufacturing, projects, warehouse/form editors, and attachment workflows
• CRM and shipping audit coverage plus startup validation surfaced through the admin diagnostics page
• backup/restore guidance, richer startup diagnostics, and exportable support bundles in the admin diagnostics workflow
• backup verification checklist and restore-drill runbook surfaced in admin diagnostics
• support-log viewing, filtering, retention cleanup, and richer support-debug export helpers in admin diagnostics
• route-level code-splitting and vendor chunking for lighter initial client loads
• file storage and PDF rendering

Product Map

Shipped phase history now lives in SHIPPED.md. ROADMAP.md now tracks remaining work only.

Current completed foundation areas:

• dashboard foundation
• CRM foundation
• inventory foundation
• sales and purchasing foundation
• shipping foundation
• projects foundation
• manufacturing foundation
• planning foundation
• audit and diagnostics foundation
• user and role administration foundation
• branding, attachments, auth/RBAC, and PDF infrastructure

Near-term priorities:

1. Deeper project-side execution visibility, cost/supply rollups, and project cockpit refinement
2. Manufacturing routing/work-center depth, labor capture, and capacity-aware execution views

Revisit / deferred items:

• local Windows Prisma migration reliability
• deeper project-side execution visibility, cost/supply rollups, and project cockpit refinement

Dashboard direction:

• the landing page is now Dashboard, not Overview
• it should remain a metric-oriented operational surface rather than a generic welcome page
• new modules should add reusable dashboard cards/panels instead of replacing the whole layout
• future additions should emphasize relevant metrics, next actions, alerts, and workflow shortcuts
• richer recent-activity widgets and exception queues are a planned QOL follow-up, not a separate landing-page redesign
• projects now feed dashboard widgets for active programs, overdue work, and risk
• manufacturing now feeds dashboard widgets for released work, overdue orders, and execution load
• planning now feeds the live workbench schedule from project and manufacturing records
• future project widgets should deepen milestones, shortages, and shipment readiness

Navigation direction:

• module navigation now uses inline SVG icons alongside labels
• new modules should add a clear, domain-appropriate SVG icon when they are added to the shell
• icons should stay lightweight, theme-aware, and dependency-free unless there is a strong reason to introduce a shared icon package

Projects Direction

Projects are now the long-running program and delivery layer for cross-module execution. The current slice ships project records with customer linkage, owner assignment, priority, due dates, milestones, project-side milestone/work-order rollups, cockpit-style commercial/supply/execution/delivery/purchasing visibility, readiness-risk scoring, a cost snapshot from linked purchasing and manufacturing data, direct launch paths into prefilled purchasing/manufacturing follow-through, an activity timeline across linked execution records, notes, commercial document links, shipment links, attachments, and dashboard visibility.

Current interactions:

• CRM: each project should link to a customer account and relevant contacts
• Sales: quotes and sales orders can already attach to projects
• Shipping: shipments tied to project deliverables are visible from the project record
• Dashboard: projects now contribute status, risk, backlog, and overdue widgets
• Detail/List UX: projects now surface milestone progress and linked execution rollups

Next expansion areas:

• Inventory: projects should reference item/BOM scope and later expose shortages or allocations
• Purchasing: project material demand is now visible through linked PO, receipt, vendor, and outstanding-supply rollups, and should later expand into project-side purchasing actions
• Manufacturing: work orders should link back to projects without turning projects into the manufacturing module
• Planning: project milestones and execution dates should feed workbench scheduling, dependency views, and richer planner drilldowns

Manufacturing Direction

Manufacturing is now a separate execution subsystem rather than being collapsed into Projects. The current slice ships work-order records with build-item linkage, optional project linkage, warehouse/location output posting, BOM-based material requirement visibility, station master data, item-level operation templates, editable station calendars and capacity settings, automatic work-order operation plans, operation-level execution controls, labor posting, operation-level rescheduling, material issue posting, completion posting, work-order attachments, and dashboard visibility.

Current interactions:

• Projects: manufacturing orders may belong to a project, but projects remain the higher-level long-running record
• Inventory: manufacturing consumes components and produces stock through real issue/receipt transactions
• Dashboard: manufacturing now contributes released/open/overdue load widgets

Next expansion areas:

• Purchasing: shortages and buyout demand should surface from manufacturing execution
• Shipping: completed manufacturing should feed shipment readiness
• Planning: manufacturing orders, routings, and work centers now drive the first capacity/load layer and should continue expanding into fuller finite-capacity scheduling

Planning Direction

Planning is now the live scheduling and visibility layer over projects and manufacturing instead of a placeholder wrapper. The current slice ships a planning workbench backed by active projects, due-date milestones, linked work orders, standalone manufacturing queue visibility, exception rails, dense load heatmaps, station load summaries, readiness scoring, overload visibility, focus-drawer inspection, planner-side operation rebalance controls including station reassignment, station-lane drag scheduling with projected load cues, planned-vs-actual station load visibility, inline release/build/buy follow-through, and agenda sequencing.

Current interactions:

• Projects: project timelines and due dates anchor the top-level planning rows
• Manufacturing: open work orders feed task rows, sequencing links, execution progress, release-ready state, and station capacity load
• Dashboard: planning now appears as a first-class module with schedule visibility links

Next expansion areas:

• Purchasing: shortages, late receipts, and vendor risk should surface directly in planning
• Manufacturing: routings, work centers, and capacity should deepen the schedule model
• Projects: richer milestones and dependency editing should extend the project-level timeline

Workspace

• client: React, Vite, Tailwind frontend
• server: Express API, Prisma, auth/RBAC, file storage, PDF rendering
• shared: shared TypeScript contracts and constants

Local Development

1. Use Node.js 22 for local development if you want Prisma migration commands to behave the same way as Docker.
2. Install dependencies with npm.cmd install.
3. Copy .env.example to .env and adjust values if needed.
4. Generate Prisma client with npm run prisma:generate.
5. Apply committed migrations with npm run prisma:deploy.
6. Start the workspace with npm run dev.

The frontend runs through Vite in development and is served statically by the API in production.

Seeded admin credentials for first login:

• email: admin@mrp.local
• password: ChangeMe123!

Docker

Build and run:

docker build -t mrp-codex .
docker run -p 3000:3000 -v mrp_data:/app/data mrp-codex

Command-line build notes:

• The Dockerfile is intended to be built directly from the repo root with docker build
• puppeteer browser download is disabled during image build because the runtime image installs system Chromium
• You can override the Node base image version if needed:

docker build --build-arg NODE_VERSION=22 -t mrp-codex .

The container startup script runs the server workspace Prisma binary directly:

/app/server/node_modules/.bin/prisma migrate deploy --schema /app/server/prisma/schema.prisma

This Docker path is currently the most reliable way to ensure the database schema matches the latest CRM and inventory migrations on Windows.

Persistence And Backup

• SQLite database path: /app/data/prisma/app.db
• Uploaded files: /app/data/uploads
• Backup the entire mounted /app/data volume to preserve both records and attachments.

CRM

The current CRM foundation supports:

• customer and vendor list, detail, create, and edit flows
• search by text plus status and state/province filters
• customer reseller flag, reseller discount, and parent-child hierarchy
• contact-history timeline entries for notes, calls, emails, and meetings
• multiple account contacts with role and primary-contact tracking
• shared file attachments on customer and vendor records
• commercial terms fields including payment terms, currency, tax exempt, and credit hold

QOL direction:

• saved filters and quick views
• cleaner hierarchy navigation for reseller/customer trees
• richer downstream rollups once purchasing and shipping grow further

Recent CRM features depend on the committed Prisma migrations being applied. If you update the code and do not run migrations, the UI may render fields that are not yet present in the database.

Inventory

The current inventory foundation supports:

• protected item master list, detail, create, and edit flows
• SKU, description, type, status, unit-of-measure, sellable/purchasable, default cost, default price, and notes fields
• BOM header and BOM line editing directly on the item form
• searchable component lookup for BOM lines, designed for large item catalogs
• SKU-first searchable component lookup for BOM lines, with SKU shown in the picker and description kept separate in the selected row
• BOM detail display with component SKU, name, quantity, unit, notes, and position
• protected warehouse list, detail, create, and edit flows
• nested stock-location management inside each warehouse record
• inventory transaction posting for receipts, issues, and adjustments
• inventory transfers with paired source/destination movement posting
• manual reservations plus automatic work-order component reservations
• item on-hand quantity, stock-by-location balances, and recent stock history
• reserved and available quantity visibility by location
• item-level file attachments for drawings and support documents
• fresh bootstrap starts inventory and warehouse data empty so first-run environments do not include demo operational records

QOL direction:

• clearer warehouse dashboards and shortage views
• BOM revisions and where-used visibility

This module introduces inventory.read and inventory.write permissions. After updating the code, restart the server against the migrated database so bootstrap can upsert the new permissions onto the default administrator role.

defaultPrice now flows from inventory items into quote and sales-order line entry when a SKU is selected. Users can still override the line price after selection.

Sales

The current sales foundation supports:

• quote and sales-order list, detail, create, and edit flows
• searchable customer lookup instead of static customer dropdowns
• SKU-searchable line entry for quote and order lines
• document-level discount, tax, freight, subtotal, and total calculations
• reseller discount defaulting from customer records into sales documents
• status quick actions directly from quote and order detail pages
• quote conversion into a sales order
• line-level unit prices populated from the selected inventory item default price
• branded quote and sales-order PDFs through the shared document pipeline
• approval stamps and revision history directly on quote and sales-order detail pages
• revision-reason capture when editing customer-facing sales documents

QOL direction:

• line duplication and faster keyboard-heavy line editing
• revision comparison view and restore-style workflows
• richer PDF output for quotes and sales orders

This module introduces sales.read and sales.write permissions. After updating the code, restart the server against the migrated database so bootstrap can upsert the new permissions onto the default administrator role.

Purchasing

The current purchasing foundation supports:

• purchase-order list, detail, create, and edit flows
• searchable vendor lookup instead of a static vendor dropdown
• SKU-searchable line entry for purchase-order lines
• purchase-order item lookup restricted to inventory items flagged as purchasable
• receiving workflow tied to purchase orders, with receipt history and inventory posting
• document-level tax, freight, subtotal, and total calculations
• quick status actions directly from purchase-order detail pages
• vendor payment terms and currency surfaced on purchase-order forms and details
• branded purchase-order PDFs through the shared document pipeline

QOL direction:

• richer dashboard widgets for vendor queues and inbound material exceptions
• vendor-side exception tracking around acknowledgements, invoice matching, and receipt discrepancies

This module introduces purchasing.read and purchasing.write permissions. After updating the code, restart the server against the migrated database so bootstrap can upsert the new permissions onto the default administrator role.

Shipping

The current shipping foundation supports:

• shipment list, detail, create, and edit flows
• searchable sales-order lookup instead of a static order dropdown
• shipment records linked directly to sales orders
• carrier, service level, tracking number, package count, notes, and ship date fields
• shipment quick status actions from the shipment detail page
• related-shipment visibility from the sales-order detail page
• branded packing-slip PDF rendering from shipment detail pages
• branded shipping-label and bill-of-lading PDF rendering from shipment detail pages
• logistics attachments directly on shipment records

QOL direction:

• reprint/history actions for generated logistics PDFs
• partial-shipment and split-shipment UX

This module introduces shipping.read and shipping.write permissions. After updating the code, restart the server against the migrated database so bootstrap can upsert the new permissions onto the default administrator role.

Moving forward, any UI that requires searching for records or items should use a searchable picker/autocomplete rather than a static dropdown. Filter controls can remain dropdowns, but non-filter lookup fields such as SKU pickers, customer selectors, vendor selectors, and similar operational search inputs should not be implemented as long static selects.

UI Density

The active client screens have been normalized toward a denser workspace layout:

• form controls and action bars use tighter padding
• CRM, inventory, warehouse, settings, dashboard, and login screens use reduced card spacing
• headings, metric cards, empty states, and long-text blocks were tightened for better data density

This denser layout is now the baseline for future screens. New pages should avoid reverting to oversized card padding, tall action bars, or long static dropdowns for operational datasets.

Branding

Brand colors and typography are configured through the Company Settings page and the frontend theme token layer. Update runtime branding in-app, or adjust defaults in the theme config if you need a new baseline brand.

Logo uploads are stored through the authenticated file pipeline and are rendered back into the settings UI through an authenticated blob fetch, so image preview works after save and refresh.

Migrations

• Create a local migration: npm run prisma:migrate
• Apply committed migrations in production: npm run prisma:deploy
• If Prisma migration commands fail on a local Node 24 Windows environment, use Node 22 or Docker for migration execution. The committed migration files in server/prisma/migrations remain the source of truth.

As of March 15, 2026, the latest committed domain migrations include:

• CRM status and list filters
• CRM contact-history timeline
• reseller hierarchy and reseller discount support
• CRM commercial terms and account contacts
• CRM lifecycle stages and operational metadata
• inventory item master and BOM foundation
• warehouse and stock-location foundation
• inventory transactions and on-hand tracking
• sales quote and sales-order foundation
• purchase-order foundation
• purchase receiving foundation
• branded sales and purchasing PDF templates
• sales approvals and document revision history
• inventory default price support
• sales totals and commercial fields
• shipping foundation
• projects foundation
• manufacturing foundation
• manufacturing stations and operation templates
• inventory transfers and reservations
• audit trail and diagnostics foundation
• auth-session visibility and revocation
• session review filters, unusual-access cues, and startup pruning of stale expired/revoked session records
• supply pegging and preferred-vendor sourcing

Recent roadmap-driving migrations should always be applied before validating new CRM, inventory, sales, shipping, or purchasing features in a running environment.

Audit And Diagnostics

The current admin operations slice supports:

• persisted audit events for core settings, inventory, purchasing, sales, project, and manufacturing write actions
• an admin diagnostics page for runtime footprint, data/storage path visibility, key record counts, and recent audit activity
• a sales-order demand-planning view with multi-level BOM netting and build/buy recommendations
• prefilled work-order and purchase-order draft launch paths from sales-order demand-planning recommendations
• shared shortage/readiness rollups across planning, project, purchasing, dashboard, and manufacturing views
• a dedicated user-management page for account creation, activation, role assignment, password reset-style updates, role-permission administration, and session visibility/revocation
• session review filters and flagged cues for stale activity, multi-session overlap, and multi-IP access patterns
• CRM customer/vendor changes and shipping mutations now flow into the shared audit trail
• startup validation now checks storage paths, writable storage readiness, database connectivity, client bundle readiness, Chromium availability, and risky production defaults during server boot
• startup now prunes stale expired or revoked auth-session records before serving requests
• backup and restore guidance now surfaces directly in diagnostics, along with exportable support bundles for support handoff
• support logs now capture startup warnings, HTTP failures, and server errors for admin-side debugging review
• support logs now support admin-side filtering by severity, source, search text, and retention window, and exports include summary metadata
• backup verification items and restore-drill expected outcomes now live in the admin runbook surface
• operator-facing review of recent high-impact changes without direct database access

Current follow-up direction:

• revision comparison UX for changed sales and purchasing documents
• deeper project-side execution visibility, cost/supply rollups, and project cockpit refinement

UI Notes

• Dark mode persistence is handled through the frontend theme provider and should remain stable across page navigation.
• The shell layout is tuned for wider desktop use than the original foundation build, and now exposes Dashboard, CRM, inventory, sales, purchasing, shipping, projects, manufacturing, settings, and planning modules from the same app shell.
• The active module screens now follow a tighter density baseline for forms, tables, and detail cards.
• The dashboard should continue evolving as a modular metric board for future purchasing, shipping, planning, and audit data.
• The client now ships with route-level lazy loading and vendor chunking, so future frontend work should preserve that split instead of re-centralizing module imports in main.tsx.

PDF Generation

Puppeteer is used by the backend to render HTML templates into professional PDFs. The current PDF surface includes the branded company-profile preview, sales quotes, sales orders, purchase orders, shipment packing slips, shipping labels, and bills of lading. The Docker image includes Chromium runtime dependencies required for headless execution.