inven/docs/architecture.md

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