Setup & usage guide

Prerequisites

Install the following before you begin:

• Node.js 20.x+ (LTS recommended)
• npm (ships with Node) or a compatible package manager
• PostgreSQL 15+ running locally or reachable over the network
• Git
• Docker & Docker Compose (optional, for containerized runs)

Installation

1. Clone the repository

git clone https://github.com/maziyank/nats.git
cd nats

2. Install dependencies

npm install

This installs Next.js, React, Prisma, UI libraries, AI clients, and development tooling defined in package.json.

Configuration

Copy the example environment file and edit values for your machine:

cp .env.example .env

Minimum variables used by the application:

Database setup

1. Create the database

psql -U postgres -c "CREATE DATABASE nats;"

2. Generate Prisma client & migrate

npx prisma generate
npx prisma migrate dev

On an existing deployment, prefer npx prisma migrate deploy so only applied migrations run.

3. Seed initial data

Choose one seed profile:

Option A — Complete seed (recommended for demos & exploration)

npx prisma db seed

Includes sample products, transactions, and bulk demo data.

Option B — Minimal seed (clean start)

npm run prisma:seed:minimal

Includes company profile, chart of accounts, and default roles/users only.

Run the application

Development server

npm run dev

Visit http://localhost:3000. The dev script frees port 3000 if needed before starting Next.js.

Production build (local)

npm run build
npm run start

Docker deployment

Use Compose when you want app + PostgreSQL together:

docker-compose up -d

Then initialize the database inside the app container:

docker-compose exec app npx prisma migrate deploy
# Full demo data
docker-compose exec app npx prisma db seed
# OR minimal
docker-compose exec app npm run prisma:seed:minimal

Default Compose services expose the app on port 3000 and Postgres on 5432 with user/password/db nats / nats_password / nats.

First login

After seeding, use these default accounts (password for all: password123):

Core workflows

Recommended first-run path after login as Super Admin:

1. Company setup — Open Admin → Settings and confirm company profile, document numbering, and storage.
2. Roles & users — Review Admin → Roles permissions, then invite or create users for each department.
3. Master data — Create contacts, departments, warehouses, product categories, and products.
4. Opening balances — Configure beginning balances and default GL accounts under Accounting configuration.
5. Operate — Run purchasing → inventory receive → sales/POS → cash/bank → financial reports.

Accounting module

Use Accounting for the full financial cycle:

• Chart of accounts — Structure asset, liability, equity, income, and expense accounts.
• Journal entries — Post double-entry journals with validation and attachments/notes where available.
• General ledger — Drill into account activity by period.
• Trial balance — Verify debits and credits before period close.
• Reports — Profit & loss, balance sheet, cash flow, equity, ratios, tax summary, and validation tools.

Inventory module

• Products — SKU, pricing, images, labels, and category assignment.
• Warehouses & locations — Multi-site stock with location detail.
• Movements — Transfers, adjustments, and batch movement forms.
• Pricing — Individual and global discount strategies.
• Reports — Low stock, slow moving, valuation, margin, and stock monitoring.

Sales & purchasing

Sales (order-to-cash)

1. Create a sales order for a customer contact.
2. Ship goods (shipment document updates inventory).
3. Issue a sales invoice and record customer payments.
4. Handle returns when needed; review AR aging and customer recap reports.

Purchasing (procure-to-pay)

1. Create a purchase order for a vendor.
2. Receive goods into a warehouse.
3. Record the purchase invoice and vendor payment.
4. Monitor AP aging, vendor recap, and tax summaries.

Point of sale

1. Open a POS session for a warehouse (optionally tag a department).
2. Scan or search products, apply discounts, hold/resume orders.
3. Checkout and print or download the receipt PDF.
4. Close the session and reconcile cash drawer balances.

POS is optimized for speed: product grid, numpad, and session controls keep cashiers productive during peak hours.

HR & payroll

• Employees — Maintain employee master records and profiles.
• Attendance & leave — Track presence and time-off requests.
• Salary structures — Define components and history per employee.
• Payroll periods — Open a period, process slips, and print payslips.

AI assistant

Admins can configure AI providers under Admin → Settings → AI. The chat interface uses configured providers (for example OpenAI or OpenRouter) to assist with business questions.

Troubleshooting

• Database connection errors — Verify PostgreSQL is running and DATABASE_URL matches host, port, user, password, and database name.
• Prisma client out of date — Re-run npx prisma generate after pulling schema changes.
• Port 3000 already in use — Stop the other process or let npm run dev free the port.
• Missing seed users — Confirm you ran a seed command and check for errors in the terminal output.
• Permission denied in UI — Sign in with a role that has the required permission, or adjust Admin → Roles.

Next: read the contribution guide if you want to fix bugs or add features, or return to the product overview.