88 lines
3.4 KiB
Markdown
88 lines
3.4 KiB
Markdown
|
# Architecture Overview
|
||
|
|
|
||
|
|
## Goal
|
||
|
|
|
||
|
|
Deliver a practical inventory and order management system that can run in a single Docker container on Unraid using SQLite for persistence.
|
||
|
|
|
||
|
|
## System Shape
|
||
|
|
|
||
|
|
The application is a monolithic web app:
|
||
|
|
|
||
|
|
- Next.js handles UI rendering and server-side actions
|
||
|
|
- SQLite stores operational and accounting data
|
||
|
|
- Server actions execute the main workflows directly against SQLite
|
||
|
|
- The same process serves UI and API endpoints
|
||
|
|
- Auth is handled in-process with a bootstrap admin user and signed session cookies
|
||
|
|
|
||
|
|
## Authentication
|
||
|
|
|
||
|
|
- The first user can be bootstrapped from `ADMIN_EMAIL` and `ADMIN_PASSWORD`
|
||
|
|
- Session cookies are signed with `AUTH_SECRET`
|
||
|
|
- Middleware protects application routes and redirects unauthenticated requests to `/login`
|
||
|
|
- This model is intentionally simple and suited to a single-container internal deployment
|
||
|
|
|
||
|
|
## Domain Boundaries
|
||
|
|
|
||
|
|
### Item Master
|
||
|
|
|
||
|
|
- `parts` stores both stocked parts and assemblies
|
||
|
|
- `kind` differentiates simple stocked parts from buildable assemblies
|
||
|
|
- Assemblies remain sellable as normal items
|
||
|
|
|
||
|
|
### Bill of Materials
|
||
|
|
|
||
|
|
- `kit_components` maps assembly items to component parts
|
||
|
|
- Building an assembly consumes component stock and creates finished stock
|
||
|
|
|
||
|
|
### Inventory Ledger
|
||
|
|
|
||
|
|
- `inventory_transactions` is the stock source of truth
|
||
|
|
- On-hand stock is derived through aggregation rather than directly edited balances
|
||
|
|
- Supported transaction types include manual adjustments, purchase receipts, sales shipments, and assembly builds
|
||
|
|
|
||
|
|
### Sales
|
||
|
|
|
||
|
|
- `customers` drives customer master data
|
||
|
|
- `sales_orders` and `sales_order_lines` capture outbound demand
|
||
|
|
- Shipping can be partial at the line level through `shipped_quantity`
|
||
|
|
- Each shipment posts inventory movements and journal entries for only the quantity moved
|
||
|
|
- Each shipment also creates a customer invoice that can later be partially or fully paid
|
||
|
|
|
||
|
|
### Purchasing
|
||
|
|
|
||
|
|
- `vendors` drives vendor master data
|
||
|
|
- `purchase_orders` and `purchase_order_lines` capture replenishment demand
|
||
|
|
- Receiving can be partial at the line level through `received_quantity`
|
||
|
|
- Each receipt posts inventory movements and journal entries for only the quantity received
|
||
|
|
- Each receipt also creates a vendor bill that can later be partially or fully paid
|
||
|
|
|
||
|
|
### Accounting
|
||
|
|
|
||
|
|
- `journal_entries` and `journal_lines` provide a lightweight operational journal
|
||
|
|
- `accounts` provides a small chart of accounts for system-posted and manual entries
|
||
|
|
- Purchase receipts debit inventory and credit accounts payable
|
||
|
|
- Sales shipments debit accounts receivable and cost of goods sold, then credit sales revenue and inventory
|
||
|
|
- Customer payments debit cash and credit accounts receivable
|
||
|
|
- Vendor payments debit accounts payable and credit cash
|
||
|
|
- Manual journals allow opening balances and non-operational bookkeeping adjustments
|
||
|
|
|
||
|
|
### Replenishment Visibility
|
||
|
|
|
||
|
|
- Low-stock reporting is derived from current on-hand balances against item reorder points
|
||
|
|
- Suggested reorder quantity is calculated from the gap between on-hand and reorder point
|
||
|
|
- The purchase order screen surfaces these items to speed up restocking decisions
|
||
|
|
|
||
|
|
## Deployment Notes
|
||
|
|
|
||
|
|
- Database file defaults to `/data/inven.sqlite`
|
||
|
|
- Next.js standalone output keeps container runtime simple
|
||
|
|
- A volume mount for `/data` preserves SQLite across container restarts
|
||
|
|
|
||
|
|
## Near-Term Expansion
|
||
|
|
|
||
|
|
- Authentication and role permissions
|
||
|
|
- Partial receipts and shipments
|
||
|
|
- Invoices, payments, and vendor bill settlement
|
||
|
|
- Warehouse or location tracking
|
||
|
|
- Reporting and export workflows
|