Lekha

Indian payroll and HRMS — employee master, attendance and leave, payroll runs with statutory deductions, income tax, loans and advances, full-and-final settlement, banking files, and an employee self-service portal.

Requirements

• Node 20+
• A PostgreSQL database. Render is what these instructions assume; any managed Postgres works.

Development

npm install
# a local Postgres, e.g. docker run -d -p 5432:5432 -e POSTGRES_PASSWORD=dev postgres:16
export DATABASE_URL="postgresql://postgres:dev@localhost:5432/postgres"
npm run db:push && npm run db:triggers
[email protected] ADMIN_NAME="Your Name" \
  COMPANY_NAME="Your Company Private Limited" npm run db:bootstrap
npm run dev

db:bootstrap creates the first company and administrator and prints a generated password once. There is no demo data and no default account.

Alternatively, visit /signup and register a company through the browser. Registration is open unless SIGNUP_ENABLED=false is set — switch it off on a single-company install, where a public page that mints administrators is not something you want.

Configuration

Copy .env.example and fill it in. In production DATABASE_URL is required — the app refuses to open a file-backed database there, because a serverless filesystem does not survive a redeploy.

Variable	Purpose
DATABASE_URL	PostgreSQL connection string. Required everywhere.
STORAGE_PROVIDER	Set to vercel-blob for this installation.
BLOB_READ_WRITE_TOKEN	Private Vercel Blob store token, server-side only.
UPLOAD_ROOT	Development only, when the Blob store is unset.
SIGNUP_ENABLED	Set to false to close self-serve registration.

Deploying to Vercel

1. Create a PostgreSQL database on Render, then copy its External Database URL into the Vercel project as DATABASE_URL. The internal URL only resolves inside Render's own network.
2. Connect a private Vercel Blob store to the project and enable its token for the target deployment environment. Set STORAGE_PROVIDER=vercel-blob. Keep BLOB_READ_WRITE_TOKEN in deployment secrets, never Git or a NEXT_PUBLIC_ variable. Existing documents in another store must be migrated separately; selecting a provider does not copy them.
3. Back up the database, then run npm run db:migrate and npm run db:check against that deployment's DATABASE_URL. The migration runner also installs the append-only audit triggers. Do not use db:push for production upgrades.
4. Deploy. Check /api/health; an administrator should also test upload, authenticated download and unauthorized access with a disposable document. A configured token is not proof that the store is reachable or its permissions are correct.
5. Bootstrap the first administrator against the same database: DATABASE_URL=… ADMIN_EMAIL=… ADMIN_NAME=… COMPANY_NAME=… npm run db:bootstrap

If a deployment comes up blank

GET /api/health reports which piece is missing — whether the database and Blob store are configured, whether the database answers, and whether the schema has been pushed at it. It reports presence, never values.

A 500 on sign-in or registration with pages that otherwise render is almost always an unset DATABASE_URL: the pages do not touch the database until something is submitted.

Known blockers before real use

These are deliberate, documented gaps rather than oversights. Read them before putting anyone's payroll in here.

• No email. There is no password reset, no invitation and no notification. An administrator issues passwords from Settings → Accounts and hands them over directly.
• Not legally certified. Core FY 2026-27 tax configuration has verification flags in lib/tax/config.ts; those flags are not certification of the whole payroll workflow. ECR and ESIC return formats remain unverified. State references, employer facts and filing outputs need independent review. See PAYROLL-AUDIT-REMEDIATION.md for implemented fixes and remaining gaps. COMPLIANCE-WORKFLOWS.md documents the statutory operations screens and migrations 0027-0034, which must be rehearsed and applied before this release.
• Tax configuration covers FY 2026-27 only. Tax cannot be computed in a financial year with no dated entry in lib/tax/config.ts. This is deliberate — silently reusing last year's slabs is worse than refusing.
• Login throttling is in-process, so it does not survive a restart or apply across instances. A shared store is needed for a real deployment.

Commands

npm run dev              # development server
npm run build            # production build
npm run db:check         # read-only check for missing release tables/columns
npm run db:push          # apply the schema
npm run db:bootstrap     # create the first company and administrator
npx tsc --noEmit -p .    # typecheck
npx tsx --test "lib/**/*.test.ts"   # unit tests
npx eslint .             # lint

Architecture notes

• Money is always integer paise, stored as bigint. No floating point anywhere in a calculation that reaches a payslip — and not 32-bit integer either, which caps at about ₹2.14 crore and would wrap silently on a large annual total.
• Business logic is pure and tested; lib/ holds the rules, Server Actions are thin wrappers over them.
• Historical figures are immutable. An approved run is the figure of record; corrections are versioned revisions and arrears, never edits.
• The audit and access logs are append-only, enforced by database triggers rather than by application convention.
• Every query is asynchronous, including inside transactions. The type-aware no-floating-promises lint rule is load-bearing: an un-awaited write inside a transaction is one the commit does not wait for.