mrp/INSTRUCTIONS.md

# Development Instructions

## 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
- sales quotes and sales orders with quick actions and quote conversion
- 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.

## 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.

## Next roadmap candidates

- shipping workflows tied to sales orders
- purchase orders and vendor-facing receiving flow
- sales and purchasing document templates
- manufacturing gantt scheduling with live project data
- broader audit and operations maturity