Development Instructions

Documentation maintenance

Keep CHANGELOG.md updated whenever shipped functionality, architecture expectations, deployment behavior, or user-facing workflows materially change.
If a change invalidates README.md, STRUCTURE.md, ROADMAP.md, or UNRAID.md, update those files in the same change set.

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
sales approvals, approval stamps, and automatic revision history 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
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
Dockerized single-container deployment
Puppeteer PDF pipeline foundation

Update the roadmap before starting large features.
Keep backend and frontend modules grouped by domain.
Add Prisma models and migrations for all persisted schema changes.
Keep uploaded files on disk under /app/data/uploads; never store blobs in SQLite.
Reuse shared DTOs and permission keys from the shared package.
Any non-filter UI that looks up records or items must use a searchable picker/autocomplete, not a long static dropdown.
Inventory items must carry both defaultCost and defaultPrice; sales documents should default line pricing from the selected item defaultPrice.
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.
Treat the landing page as Dashboard: a metric-oriented, modular command surface that should accumulate reusable operational panels over time.
Purchase-order item selection must be restricted to inventory items where isPurchasable = true.
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.
Keep Projects, Manufacturing, and Planning distinct: projects are long-running program records, manufacturing is execution, and planning is scheduling/visibility.
New top-level modules added to the app shell should include a matching SVG icon in navigation so the module list remains visually scannable.

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.