initial release testing

docs/adr/0001-monolith-nextjs-sqlite.md

@@ -0,0 +1,55 @@
+# ADR 0001: Use a Next.js Monolith with SQLite for Initial Deployment
+
+- Status: Accepted
+- Date: 2026-03-23
+
+## Context
+
+The system needs to support inventory management for stocked parts and assemblies, sales orders and shipping, purchase orders and restocking, customer and vendor records, and an initial accounting module. The first deployment target is a single Docker container on Unraid with SQLite as the database.
+
+## Decision
+
+Use a single Next.js application with TypeScript and SQLite.
+
+Key aspects:
+
+- UI and backend live in one deployable unit
+- SQLite is the primary datastore and is persisted through a mounted `/data` volume
+- Inventory is modeled as a transaction ledger, not an editable balance table
+- Assemblies are first-class items with bill-of-material component records
+- Accounting starts as an operational journal tied to stock-affecting workflows
+
+## Alternatives Considered
+
+### Separate frontend and API services
+
+Rejected for now because it adds deployment and operational complexity that does not help the initial Unraid target.
+
+### Python monolith
+
+Reasonable, but not selected because the project defaults favor TypeScript for full-stack work and Next.js gives a fast path to a polished UI and server-rendered workflows in one application.
+
+### Direct quantity-on-hand fields without a transaction ledger
+
+Rejected because the system needs reliable traceability for receipts, builds, shipments, and later accounting reconciliation.
+
+## Consequences
+
+### Positive
+
+- Simple deployment model
+- Minimal infrastructure requirements
+- Clear path from operational workflows to accounting entries
+- Good developer velocity for admin and internal-tool style features
+
+### Negative
+
+- SQLite concurrency limits will eventually matter at larger scale
+- Server actions are tightly coupled to the app process
+- Accounting capabilities are intentionally lightweight at this stage
+
+## Follow-Up
+
+- Add auth and permissions before multi-user production rollout
+- Add partial receipt and shipment workflows
+- Add lockfile and CI once dependencies can be installed in a build-capable environment

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