inven/README.md

# Inven

Inven is a single-container inventory management system for Unraid-style deployments. It manages stocked parts, assemblies built from parts, sales orders and shipping, purchase orders and restocking, customers, vendors, and a lightweight accounting journal on top of SQLite.

## Current Scope

- Parts and assemblies share one item master
- Assemblies support bill-of-material component definitions
- Inventory is tracked through a transaction ledger
- Sales orders can be created and shipped
- Purchase orders can be created and received
- Sales orders and purchase orders are created from relational inventory line selections
- Sales orders support partial shipments
- Purchase orders support partial receipts
- Invoices are generated from shipped sales orders
- Vendor bills are generated from received purchase orders
- Customer and vendor payments can clear receivables and payables
- Customer and vendor directories support the order flows
- Low-stock and suggested reorder views help drive replenishment
- A chart of accounts, account balances, and manual journals support the first accounting pass
- Built-in authentication protects the app with a bootstrap admin login

## Stack

- Next.js App Router
- TypeScript
- SQLite via `better-sqlite3`
- Single Docker container with Next.js standalone output

## Quick Start

1. Install Node.js 22 or newer.
2. Copy `.env.example` to `.env`.
3. Set `AUTH_SECRET`, `ADMIN_EMAIL`, and `ADMIN_PASSWORD`.
4. Update `DATABASE_PATH` if needed.
5. Install dependencies:

```bash
npm install
```

6. Start the development server:

```bash
npm run dev
```

7. Open `http://localhost:3000` and sign in with the bootstrap admin credentials.

The SQLite schema is created automatically on first run.
If the database has no users yet, the bootstrap admin user is created from `ADMIN_EMAIL` and `ADMIN_PASSWORD`.

## Docker

Build and run locally:

```bash
docker build -t inven .
docker run --rm -p 3000:3000 -v $(pwd)/data:/data inven
```

Suggested Unraid mapping:

- App data mount: `/data`
- Container port: `3000`
- Environment variable: `DATABASE_PATH=/data/inven.sqlite`
- Environment variable: `AUTH_SECRET=<long random secret>`
- Environment variable: `AUTH_SECURE_COOKIES=false` for plain HTTP on a LAN, `true` only behind HTTPS
- Environment variable: `ADMIN_EMAIL=<admin email>`
- Environment variable: `ADMIN_PASSWORD=<initial admin password>`

## Workflow Notes

- Add customers and vendors before creating orders.
- Add parts and assemblies in the Parts module.
- Define assembly components in the Assemblies module.
- Create SOs and POs by selecting actual inventory items from the item master instead of typing free-form SKUs.
- Use purchase orders to restock and receive inventory.
- Use build transactions to convert component stock into assembly stock.
- Use sales orders and ship them fully or partially to reduce stock and generate invoices plus journal entries.
- Use purchase orders and receive them fully or partially to increase stock and generate vendor bills plus journal entries.
- Use the Invoices page to receive customer payments against open AR.
- Use the Vendor Bills page to pay vendor obligations against open AP.
- Use the accounting page to add accounts, review balances, and post manual journals when needed.
- Use the login page to access the application with the configured admin account.

## Known Gaps

- No lot, serial, warehouse, or bin tracking yet
- No lockfile included because dependencies were not installed in this environment

## Project Docs

- [Architecture overview](./docs/architecture.md)
- [ADR: monolith stack and data model](./docs/adr/0001-monolith-nextjs-sqlite.md)
- [Unraid installation guide](./UNRAID.md)