mrp/STRUCTURE.md

# Project Structure

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

## Backend rules

- Organize domain modules under `src/modules/<domain>`.
- Keep HTTP routers thin; place business logic in services.
- Centralize Prisma access, auth middleware, and file storage utilities 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.