mrp/INSTRUCTIONS.md

# Development Instructions

## Documentation maintenance

- Keep [CHANGELOG.md](D:/CODING/mrp-codex/CHANGELOG.md) updated whenever shipped functionality, architecture expectations, deployment behavior, or user-facing workflows materially change.
- If a change invalidates [README.md](D:/CODING/mrp-codex/README.md), [STRUCTURE.md](D:/CODING/mrp-codex/STRUCTURE.md), [ROADMAP.md](D:/CODING/mrp-codex/ROADMAP.md), [SHIPPED.md](D:/CODING/mrp-codex/SHIPPED.md), or [UNRAID.md](D:/CODING/mrp-codex/UNRAID.md), update those files in the same change set.

## Current milestone

This repository implements the platform foundation milestone:

- workspace scaffolding
- local auth and RBAC
- company settings and branding
- file attachment storage
- CRM foundation through reseller hierarchy, contacts, attachments, and lifecycle metadata
- inventory master data, BOM, warehouse, stock-location, transactions, and item attachments
- inventory transfers, reservations, available-stock visibility, and work-order reservation automation
- inventory SKU master builder with family-scoped sequence generation and branch-aware taxonomy management
- inventory thumbnail image staging on create/edit and dedicated thumbnail display on item detail
- sales quotes and sales orders with quick actions and quote conversion
- sales approvals, approval stamps, automatic revision history, and revision comparison on quotes and sales orders
- purchase orders with quick actions and searchable vendor/SKU entry
- purchase orders restricted to inventory items flagged as purchasable
- purchase receiving foundation with inventory posting and receipt history
- purchase-order revision history and revision comparison across document and receipt changes
- branded sales and purchasing PDFs through the shared Puppeteer document pipeline
- purchase-order supporting documents and vendor-side purchasing visibility
- 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, notes, attachments, and dashboard visibility
- manufacturing work orders with project linkage, station master data, item operation templates, auto-generated work-order operations, attachments, and dashboard visibility
- planning gantt timelines backed by live project and manufacturing schedule data
- sales-order demand planning with multi-level BOM explosion, net stock/open-supply coverage, and build/buy recommendations
- planner-assisted conversion of demand-planning recommendations into prefilled work-order and purchase-order drafts
- pegged work-order and purchase-order supply coverage tied back to sales demand, with preferred-vendor sourcing defaults
- shared shortage and readiness rollups across dashboard, planning, projects, purchasing, and manufacturing
- admin diagnostics with runtime footprint, storage visibility, record counts, and recent audit activity
- admin user management with account creation, activation, role assignment, role-permission editing, session visibility/revocation, and review filtering
- safer destructive-action confirmations and recovery messaging across admin, sales, purchasing, shipping, inventory, manufacturing, projects, warehouse/form editors, and attachment workflows
- CRM/shipping audit coverage and startup validation surfaced through diagnostics
- backup/restore guidance, richer startup diagnostics, and exportable support bundles in diagnostics
- backup verification checklist and restore-drill runbook in diagnostics
- support-log viewing, filtering, retention cleanup, and support debugging helpers in diagnostics
- startup brand-theme hydration so Company Settings colors persist correctly across refresh
- Dockerized single-container deployment
- Puppeteer PDF pipeline foundation

## Workflow

1. Update the roadmap before starting large features.
2. Keep backend and frontend modules grouped by domain.
3. Add Prisma models and migrations for all persisted schema changes.
4. Keep uploaded files on disk under `/app/data/uploads`; never store blobs in SQLite.
5. Reuse shared DTOs and permission keys from the `shared` package.
6. Any non-filter UI that looks up records or items must use a searchable picker/autocomplete, not a long static dropdown.
7. Inventory items must carry both `defaultCost` and `defaultPrice`; sales documents should default line pricing from the selected item `defaultPrice`.
8. Maintain the denser UI baseline on active screens; avoid reintroducing oversized `px-4 py-3` style controls, tall action bars, or overly loose card spacing without a specific reason.
9. Prefer concise uppercase module and section labels in the live interface, and avoid redundant descriptive subcopy when the surrounding data already makes the purpose clear.
10. When designing operational pages, bias toward information density: tighter panel padding, smaller stack gaps, and fewer explanatory filler blocks.
11. Treat the landing page as `Dashboard`: a metric-oriented, modular command surface that should accumulate reusable operational panels over time.
12. Purchase-order item selection must be restricted to inventory items where `isPurchasable = true`.
13. Treat `Projects` as a first-class cross-module domain tying together CRM, sales, inventory, purchasing, shipping, and planning; do not bury it as a one-off manufacturing subfeature.
14. Keep `Projects`, `Manufacturing`, and `Planning` distinct: projects are long-running program records, manufacturing is execution, and planning is scheduling/visibility.
15. New top-level modules added to the app shell should include a matching SVG icon in navigation so the module list remains visually scannable.

## Operational notes

- Run `npm run prisma:generate` after schema changes.
- Run `npm run prisma:migrate` during development to create versioned migrations.
- Use `npm run prisma:deploy` in production environments.
- Prefer Node 22 locally when running Prisma migration commands to match the Docker runtime.
- Branding defaults live in the frontend theme token layer and are overridden by the persisted company profile.
- Back up the whole `/app/data` volume to capture both the database and attachments.
- Treat searchable lookup as a standing UX requirement for inventory, BOM, sales, purchasing, manufacturing, customer, vendor, and other operational record-picking flows. Filter-only controls can still use dropdowns.
- Extend the existing Puppeteer document pipeline when adding customer-facing or logistics PDFs instead of creating a parallel export mechanism.
- Add future dashboard features as modular metric/action panels instead of one-off hero sections or static marketing-style content.
- When implementing projects, model the relationships explicitly so project records can anchor execution across customer, order, material, schedule, and shipment workflows.
- When implementing manufacturing, keep work orders, routings, labor, and shop-floor execution in their own domain rather than collapsing them into projects.

## Next roadmap candidates

- project milestones and project-side rollup visibility
- manufacturing routing/work-center depth, labor capture, and capacity-aware execution views