initial release testing

docs/architecture.md

@@ -0,0 +1,87 @@
+# 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