A Modern, Medium Scale - Multi-Tenant Construction ERP

Organization & Company Model

A tenant organisation can act as an umbrella containing multiple legal companies (such as a holding group, sister concerns, or entities with separate GSTINs).

• Each company has its own GSTIN, address, bank details, signature, and official seal.
• Each company can independently connect to Zoho Books with its own exclusive OAuth grant.
• All sales documents (quotations, invoices, RA bills, credit notes) are issued on behalf of a chosen company. The system automatically merges the selected company's bank metadata, signature, and seal into the rendered PDFs.
• Billing Company Lock: Customer records are permanently locked to a billing company once the first approved document is issued, preventing accidental cross-entity invoicing.
• Per-tenant branding (logo, accent colour, brand mark) is isolated, while the Superadmin separately controls the platform-level brand that appears on global auth screens.

Module Catalogue

The ERP Home (/) presents a card grid of modules. A Quick Create strip on the home screen exposes a configurable 4×1 grid of one-tap entry points (e.g. New Invoice, New Project, New PO, New Advance) — filtered automatically by the modules the current user is permitted to access.

Detailed Capabilities by Module

5.1 Sales Module

Pages: Dashboard, Customers, Quotations, Invoices, Credit Notes, Proforma, RA Bills (project view), Project Dashboard, All Invoices.

• Customer master: Separation of Trade Name (legal) vs display_name (unique nickname), billing/shipping address mapping, GSTIN, default-type sync, and optional manual Zoho contact ID bypass for legacy migration.
• Quotations: General vs Special Terms & Conditions, default unit logic, configurable signature blocks, and polished PDF exports.
• Direct Invoices: Pre-filled default T&C, calculated due dates from payment terms, sequential numbering, and dual-mode PDFs (Detailed line-items vs Summary).
• Shadow item compliance: Non-billable line items can be carried for record-keeping without distorting real tax totals.
• Negative-quantity blocking: Hard blocks at the form level prevent accidental refund-shaped invoices.
• Credit Notes: Automatic IGST vs CGST routing based on place-of-supply, fully linked to the source invoice and mapped to the matching Zoho credit note.
• Proforma Invoices: Separate numbering series with a clear "not-for-tax" stamp.

5.2 Project Management Module

Pages: Projects, Project Detail, Master Items, RA Bills, RA Bill Edit, RA Bill View.

• A unique project_id consistent across Inventory (locations, transfers), HRM (attendance, payroll), and Sales (RA bills).
• An auto-generated location entity so that the project's site address acts as a real inventory location for material transfers.
• A Master Items list with per-item HSN and GST mappings inherited from the global item master.
• A Financial Summary showing total contracted value, total billed, holds outstanding, and net balance.

5.3 Purchase Module

Pages: Dashboard, Vendors, Orders, Transactions, Credit Notes.

• Vendor master: GSTIN, payment terms, bank details, and Zoho vendor mapping.
• Purchase Orders: Drag-drop item selection, automatic billing company resolution, and signature-bearing PDFs.
• Purchase Transactions: Vendor invoice number priority (the vendor's invoice # takes precedence over the internal reference for matching), and per-line tax-rate overrides for special cases.
• Purchase Credit Notes: Full synchronization with Zoho.
• AI Document Extraction: Purchase invoice images are parsed by Gemini 2.5 Flash to automatically pre-fill line items, GSTIN, and totals.

5.4 Inventory & Equipment Module

Pages: Dashboard, Material, Machinery, Locations, Location Detail, Transactions, Audit Trail, Stock Movements.

• Item master (materials): Configured with HSN, GST, units, categories, average cost, and price history tracking.
• Machinery master: Dedicated repair management, live working status tracking, and machinery-specific stock dialogs.
• Locations: Physical sites, central warehouses, and auto-generated project locations.
• Transactions: Purchase, Consumed, Lost, Scrapped, Purchase Return, and Reconciliation. Each transaction rigorously captures Name + Email + Timestamp into audit_logs.
• Reconciliation (RCN): Unifies consumption and material transfers into a single flat reconciliation event without spawning messy child records, preserving a clean audit story.
• Audit Trail: Deep views into single item histories and comprehensive stock comparisons.

5.5 HRM Module

Pages: Dashboard, Onboarding, Employees, Masters, Attendance, Records, Payments, Slips, Settings.

• Onboarding: Pending status queues, bulk Excel upload, and strict master data validation.
• Employee master: Aadhaar validation, rigid salary structures, fixed deductions, and bank/UPI details.
• Attendance Entry: Sundays visually highlighted (as advance days), featuring a minimised summary panel for daily totals.
• Quick Pay UPI & Exports: One-tap UPI deep-link payments with built-in boundaries, plus pre-formatted bulk bank export CSVs for ICICI, HDFC, and SBI corporate banking templates.

5.6 Workspace Module

Pages: Dashboard, Files, Company Documents, Recent Activity, Trash.

• Backed securely by the organisation's connected Google Drive.
• Mirrors the ERP hierarchy: Customers, Vendors, Projects, and RA Bills each get their own folder tree automatically maintained inside Drive.
• Auto-recovery triggers: If a folder is manually deleted in Drive, the next ERP write automatically recreates it.
• Important file lock: Files marked "important" cannot be deleted without an explicit secondary unlock.

5.7 Analytics & 5.8 Finance

• Analytics: Strictly Admin-only. Cross-module roll-ups pull from Inventory consumption, HRM payroll, and Sales billing to calculate accurate project profitability and cost-vs-budget.
• Finance & Accounting: An admin-only bridge router that opens the connected company's Zoho Books in a new tab. No accounting UI is duplicated inside the ERP — the system defers entirely to Zoho as the system-of-record.

5.9 Administrator & 5.10 SuperAdmin

• Administrator: Manage org users, pre-invites, soft-deletes, email changes, companies, signatures, seals, bank details, and all numbering series with default T&Cs.
• SuperAdmin: Platform-level control. Approves, disables, or deletes tenant organisations. Toggles specific modules per organisation, manages public sign-ups, views platform-wide analytics, and manages the global auth screen branding.

Feature Deep Dives

6.1 RA Bill Engine (Running Account Bills)

Running Account Bills are the absolute heart of construction billing. Each RA bill represents the cumulative quantity executed on each line item up to a given date, with the new bill's value being the exact delta against the previous bill.

Export Capabilities: RA Bills support nested attachments (drawings, photos) that travel with the bill into PDF exports. PDFs utilize Arial-only typography for crisp printing, with configurable display filters. Furthermore, a bill can be cloned directly into a Google Sheet via the Sheets API, preserving the exact ERP layout.

6.2 HRM Payroll Engine

• Recursive balance walk: Rolling balances (advance, deduction, pending dues) are computed by an explicit loop walking from the employee's first-ever entry forward, ensuring a stable result independent of grid order.
• -1 sentinel: The grid distinguishes three states: a real value, a manually-entered zero, and a "deleted" cell. The sentinel -1 represents deletion so downstream aggregations can ignore it without losing audit history.
• Debounced calculations & 2-decimal constraints: Cell edits trigger debounced recomputes to avoid thrash on fast typists, while money columns strictly enforce 2 decimals at the database schema level.
• Sunday weekly cycle: Submissions are gated to Sundays, ensuring uniform week boundaries across projects.
• Slip PDF generation: Slips are rendered into a fixed-width 794px off-screen HTML node and then captured to canvas, producing pixel-perfect A4 PDFs irrespective of the user's viewport.

6.3 Inventory Transfers

A three-stage transfer workflow ensures physical material movements are reflected accurately in stock without double-counting:

• A SECURITY DEFINER RPC enforces the strict progression rule — clients cannot revert a transfer backwards, even with crafted API requests.
• Stock movements are committed only on DELIVERED, completely eliminating the common "lost-in-transit" double-counting problem.
• Permissions are strictly tier-checked: managers can advance stages, but only admins can hard-cancel a delivered transfer.

6.4 Customer, Invoice & Quotation Systems

• Identity & Address Model: Trade Name is the legal name printed on invoices, while display_name is a unique short nickname used internally. Billing and shipping addresses are first-class entities; project addresses inherit automatically.
• Billing Company Lock: Once a customer's first approved document is issued from a particular company, that pairing is securely locked to prevent accidental cross-entity invoicing.
• Quotation Settings: Features General T&C applied by default, Special T&C appended per quote, configurable Signature blocks, and Default units resolved directly from the item master.

Deep Integrations

7.1 Zoho Books

The ERP treats Zoho Books as the final accounting system-of-record. The integration features:

• OAuth: Per-company OAuth grant with refresh-token rotation handled by edge functions.
• Identity matching: Customers and vendors are intelligently matched by GSTIN + display name.
• Tax Mappings: Items are tax-classified by HSN, and a dedicated TDS settings card maintains live mapping between local TDS codes and Zoho withholding tax IDs.
• Sync Surface: Fully covers sync-invoice, creditnote, customer, vendor, purchase-bill, purchase-creditnote, and ra-invoice. Sync is strictly restricted to GST-registered counterparties by design. Each entity explicitly displays its Zoho sync metadata (last synced, Zoho doc ID, status).

7.2 Google Drive (Workspace)

• Security: AES-256-GCM encryption of OAuth tokens at rest, utilizing an In-Production consent screen.
• Mirrored hierarchy: The ERP automatically creates and maintains a Drive folder tree that perfectly mirrors Customers, Vendors, Projects, and RA Bills.
• Auto-recovery: If a mirrored folder is deleted directly in Google Drive, the next ERP write transparently recreates it. Cross-org access is mathematically impossible due to strict per-org token isolation.

7.3 Lovable AI Gateway & 7.4 GSTIN

• Lovable AI: A single managed AI gateway (using Gemini and GPT-5 families) powers Smart Search (⌘K) for natural-language routing, a context-aware floating Chat Assistant, a Document Summarizer, and automated Purchase Image Extraction.
• GSTIN Verification: Edge functions actively validate entered GSTINs against the official Indian government registry, returning the precise legal name, address, and registration status during customer/vendor onboarding.

UI, UX & Realtime Notifications

• Visual Language: Zoho Books-inspired minimalism featuring generous whitespace in light mode, and high-density alternating rows (#111827 / #1a2332) in dark mode. Theme toggle covers Light, Dark, and System states.
• Colour Discipline: Amber is reserved exclusively for warnings and pending statuses.
• Unified Navigation: A top-3 floating sidebar toggle and a unified header that consolidates AI search, theme, notification bell, and the Superadmin context banner.
• Dialog Pattern: All modals follow a strict max-h-[90vh] overflow-hidden flex-col shell with a flexible scrolling body, guaranteeing native scrolling behaviour even for massive forms. Responsive table wrappers gracefully fall back to horizontal scrolling without sacrificing column widths on mobile.
• Notifications & Transport: The Notification Bell surfaces server-side filtered alerts via Supabase Realtime postgres_changes, backed by a robust 60-second fallback poll ensuring zero missed alerts during mobile network handoffs.

Operational Capabilities

Glossary of Terms