Paravalves Platform
Unified ERP + CRM + Engineering + Inventory + Procurement + Projects + Finance for Paravalves.
One relational source of truth from website inquiry through to project closure — no parallel Excel.
See BUILD_PLAN.md for the full architecture and phased specification.
Stack
| Layer | Technology |
|---|
| App | Next.js 15 (App Router) · React 19 · TypeScript (strict) |
| Database | PostgreSQL 16 (hand-written SQL migrations) |
| DB access | pg with a typed query/transaction helper |
| Auth | Custom session auth (scrypt + server-side sessions, HttpOnly cookie) |
| Authorization | Permission codes + roles, enforced server-side, org-scoped |
| Money | decimal.js (never floats); server recomputes all totals |
| Validation | Zod |
| Styling | Tailwind CSS + hand-built component primitives |
| Tests | Vitest |
| Dev DB | Docker Compose Postgres on port 55432 |
Quick start
npm install
npm run db:up # start Postgres (docker) on :55432
npm run db:migrate # apply schema
npm run db:seed # roles, permissions, orgs, admin user, sample data
npm run dev # http://localhost:3000
Login:
Scripts
| Command | Purpose |
|---|
npm run dev | Dev server |
npm run build / npm start | Production build / serve |
npm run typecheck | tsc --noEmit |
npm run lint | ESLint |
npm run test | Vitest unit tests |
npm run db:migrate / db:seed / db:reset | Database lifecycle |
What's implemented
- Auth & RBAC — sessions, 8 seeded roles, permission-gated routes, org (India/Spain) scoping, audit of auth events.
- CRM — leads (pipeline + stage machine), companies (Company 360), contacts, activity timelines, convert-to-customer (reuses existing company — no duplicate data).
- Website inquiry API —
POST /api/public/inquiry, hardened (shared secret, rate limit, honeypot, duplicate detection) → lead → assignment → follow-up task → notification.
- Quotations — line editor, server-side tax/total engine, state machine, one-click Quote → Sales Order (carries everything, idempotent).
- Sales Orders — the signature Order 360 screen, gated workflow (drawing-approval and material gates), invoice generation.
- Products & part numbers — product master with duplicate prevention; configurable, collision-safe part-number engine with revisions.
- Engineering — drawings with revisions and
DRAFT→…→RELEASED approval; releasing a drawing clears the order's engineering gate.
- Inventory & MRP — stock ledger (append-only movements), concurrency-safe reservation, material-requirement intelligence (required/available/incoming/shortage).
- Procurement — purchase orders + goods receipt (accepted qty increases stock; recomputes shortages).
- Projects — auto-created from orders, phase progress roll-up, mandatory closure gates.
- Finance — GST-correct tax invoices (CGST/SGST vs IGST vs export), payments with allocation and receivables.
- Tasks, notifications, global search, admin, health/ready endpoints.
Numbering
Concurrency-safe, per-org, per-year: LEAD-2026-000001, SO-2026-000012, INV-2026-000003, etc.
Generated by a single atomic upsert so two users can never receive the same number.
Security highlights
- Every mutating path runs server-side through a domain service that checks permission and org scope.
audit_logs and stock_movements are append-only at the database level (triggers / insert-only).- Optimistic concurrency (
version column) prevents silent overwrites → 409 CONFLICT.
- Public inquiry endpoint can only insert; it can never read internal data.
- Security headers + CSP in
next.config.mjs; secrets only in .env (gitignored).
Environment
Copy .env.example to .env. .env is generated with fresh secrets on first setup.
Key vars: DATABASE_URL, SESSION_SECRET, WEBSITE_INQUIRY_API_KEY, MAIL_DRIVER.
