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:

• [email protected] / admin123 — Super Admin (India + Spain)
• [email protected] / sales123 — Sales (India)

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.