# 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