mrp/STRUCTURE.md

Project Structure

Documentation maintenance

• Keep CHANGELOG.md updated when structural or implementation changes materially affect shipped behavior.
• If structure guidance changes, update the related source-of-truth docs in README.md, INSTRUCTIONS.md, ROADMAP.md, UNRAID.md, and AGENTS.md as needed.

Top-level layout

• client/: frontend application
• server/: backend application
• shared/: shared TypeScript contracts, permissions, and utility types
• Dockerfile: production container build
• docker-entrypoint.sh: migration-aware startup script

Frontend rules

• Organize code by domain under src/modules.
• Keep app-shell concerns in src/app.
• Keep reusable UI primitives in src/components.
• Theme state and brand tokens belong in src/theme.
• PDF screen components must remain separate from API-rendered document templates.
• Treat src/modules/dashboard as a long-lived operational module. New high-level KPI, alert, queue, and shortcut surfaces should compose into it rather than spawning disconnected landing pages.
• Any non-filter lookup UI must be implemented as a searchable picker or autocomplete; do not use long static dropdowns for operational datasets such as items, customers, vendors, or document-linked records.
• Inventory items expose both cost and sell price. Downstream sales document entry should default from the item price field rather than requiring duplicate price maintenance.
• Future vendor-facing purchasing flows should follow the same searchable-lookup rule and shared document/totals model already used by sales.
• Purchase-order item pickers must only surface inventory items flagged as purchasable.
• Shipping, sales, and future purchasing PDFs should be rendered through the backend documents module and shared Puppeteer pipeline rather than ad hoc frontend-only exports.
• Preserve the current dense operations UI style on active module pages: compact controls, tighter card padding, and shorter empty states unless a screen has a clear reason to be more spacious.
• Treat projects as its own long-lived domain under both client and server. It should continue integrating with CRM, sales, inventory, purchasing, shipping, and planning rather than living inside only one of those modules.
• Treat manufacturing as a separate long-lived domain from projects; work orders, routings, labor capture, WIP, and shop-floor execution should not be modeled only as project fields.
• Treat planning as the scheduling/visibility layer that consumes project and manufacturing data rather than replacing either domain.
• When adding a new top-level module to the shell, add a lightweight SVG icon in the navigation config so desktop and mobile nav stay aligned.

Backend rules

• Organize domain modules under src/modules/<domain>.
• Keep HTTP routers thin; place business logic in services.
• Centralize Prisma access, auth middleware, persisted session helpers, file storage utilities, startup validation, and support logging in src/lib.
• Store persistence-related constants under src/config.
• Serve the built frontend from the API layer in production.

Shared package rules

• Place cross-app DTOs, permission keys, enums, and document interfaces in shared/src.
• Keep shared code free of runtime framework dependencies.

Adding a new domain

1. Add backend routes, service, and repository/module files under server/src/modules/<domain>.
2. Add Prisma models and a migration if the module needs persistence.
3. Add permission keys in shared/src/auth.
4. Add frontend route/module under client/src/modules/<domain>.
5. Register navigation and route guards through the app shell without refactoring existing modules.