InvoSpark ERP | Multi-Branch Financial & Inventory System
Project Overview
InvoSpark ERP is an enterprise-grade multi-branch Enterprise Resource Planning (ERP) platform designed for complex retail, supply chain, and multi-currency environments. Built with a modern decoupled stack featuring NestJS 11, Prisma ORM with PostgreSQL, and Next.js 15 (App Router), the platform provides strict transactional ACID guarantees, an immutable stock ledger audit trail, accounting cancellation guardrails, and real-time multi-branch inventory synchronization.
Senior Architectural & Financial Engineering Highlights
Embedded Payment Engine & Atomic Vouchers
Engineered atomic payment workflows executing voucher generation during purchasing/sales invoicing. Encapsulates payment allocation logs and financial vouchers inside single Prisma $transaction blocks to guarantee zero-discrepancy ledger updates.
Immutable Stock Ledger & Running Balance
Architected a document-driven inventory ledger recording every stock movement (SALE, RETURN, ADJUSTMENT) alongside prior and updated running balances for complete audit trail transparency.
Cancellation Guardrails & Accounting Safeguards
Implemented strict financial guards preventing invoice deletion or cancellation when linked to active sales returns, maintaining strict balance sheet alignment and avoiding unrecorded inventory leaks.
Multi-Currency & Historical FX Rate Freezing
Stores dual-currency entries alongside locked exchange rates (exchangeRate, totalInBaseCurrency), ensuring macro-economic fluctuations do not distort past financial statements.
Optimistic Concurrency & Race Condition Prevention
Guarded stock inventory against concurrent branch transactions using version-based optimistic locking (ProductBranch.version) to prevent race conditions during peak checkout periods.
Real-Time WebSockets & Branch-Scoped Rooms
Built a Socket.IO gateway broadcasting instant notifications for low-stock threshold breaches and voucher allocations across isolated branch rooms (branch_id).
System Showcase & Detailed Workflows
Executive Financial Dashboard & Real-Time Analytics
Engineered an executive financial dashboard delivering real-time business KPIs. Features dynamic computation pipelines tracking Gross vs. Net revenues (net of returns), automated COGS-derived Gross Profit Margin (%), dual-currency aggregation (USD/SYP), and multi-branch liability totals.
Multi-Branch Product Directory & Pricing Engine
Architected a centralized product catalog managing enterprise master data (SKUs, Categories, Dual-Currency Pricing). Features a popover visual overlay for real-time Branch Availability, enforcing transactional inventory consistency across isolated operational units.
Global Stock Ledger & Immutable Audit Trail
Architected an immutable, transaction-driven Global Stock Ledger logging line-item movements (Sales, Purchases, Returns, Adjustments). Computes precise prior and updated running balances with mandatory timestamps and user attributions for audit reconciliation.
Proactive Low-Stock Alerting & Suggested Actions
Integrated a reactive stock-monitoring engine that evaluates real-time inventory against dynamic reorder thresholds. Triggers low-stock alerts and suggests immediate business workflows (e.g., Create Purchase Order).
Multi-Currency Invoicing, Partial Returns & Accounting Guardrails
Engineered an end-to-end sales invoicing pipeline supporting dual-currency POS operations (USD/SYP rate freezing), line-item savings tracking, and dynamic 15% VAT calculations. Reconciles partial customer returns by pro-rating tax reversals and recalculating Net Totals (transitioning status to PARTIALLY REFUNDED), while enforcing strict accounting guardrails that lock invoice cancellation when linked to active return entries.
Sales Invoices Directory & Real-Time Revenue Aggregation
Engineered a centralized sales invoice management directory with real-time aggregate metrics (Page Total, Paid Amount, Remaining Balance). Features multi-parameter filtering (status, date ranges, full-text search), visual strikethrough pricing for partially refunded invoices, and seamless dual-currency state tracking.
Omni-Channel Returns Directory & Granular Refund Audit Modal
Architected a unified returns management system handling both Customer (Sales) and Supplier (Purchase) return workflows. Features a centralized registry linked to original invoice references, paired with a modal inspector that calculates itemized refund breakdowns, enforces historical exchange rate freezing (1 USD = 14,000 SYP), applies pro-rated 15% VAT reversals, and logs mandatory return reason codes for audit compliance.
Supplier Ledger Audit Trail & Running Balance Engine
Architected a double-entry supplier ledger computing real-time running balances (CR/DR). Accurately reconciles purchases, returns, inline invoice payments, and standalone vouchers with full multi-currency conversion tracking.
Dual-Currency Purchasing, Payment Allocations & AP Ledger Synchronization
Engineered an atomic purchasing and Accounts Payable (AP) workflow supporting dual-currency transactions (USD/SYP exchange rate freezing). Features multi-stage payment processing (embedded at creation or via standalone supplier vouchers), real-time payment allocation logging, automatic remaining balance computation (Balance Due), and live ledger synchronization updating supplier credit/debit totals across branch directories.
Role-Based Security Architecture & Instant Multi-Role Demo Access
Engineered a granular Role-Based Access Control (RBAC) security framework with strict UI/API data-masking layers across 4 operational roles (Super Admin, Accountant, POS Cashier, Inventory Manager). Restricts sensitive financial metrics for warehouse staff, isolates POS transactions, and enforces branch-scoped data security. Features instant one-click demo credentials directly on the landing page for live role-switch testing.
Role-Based Access Control (RBAC) & Multi-Branch Access Scoping
Configured multi-tenant enterprise security with granular domain permissions, role-based navigation guards, dynamic branch context switching, and isolated data visibility across operational units.
Account Security & Password Lifecycle Management
Implemented enterprise authentication controls including strict password policy validation, secure JWT refresh session lifecycles, and audit logging for account governance.
System Architecture & Technology Stack
01. Backend & Financial Engine
- Framework: NestJS 11 (Node.js 22), TypeScript / Node.js
- ORM & Database: Prisma 5.22, PostgreSQL 16
- Caching & Queues: Redis 7 (Service Containers)
- Real-Time Gateway: Socket.IO WebSockets
- Reporting Engine: Puppeteer (PDF Rendering), Cloudinary
02. Frontend & State Management
- Framework: Next.js 15 (App Router), React 18
- Design System: Tailwind CSS 3.4, shadcn/ui
- State & Server Query: Zustand, TanStack React Query
- Forms & Data Viz: React Hook Form, Zod, Recharts
- Precision Math: Decimal.js, Currency.js, Date-fns
03. DevOps, Security & Audit
- Containerization: Docker & Multi-stage Docker Compose
- Web Server: Nginx (Production Reverse Proxy)
- Cloud Platform: Render Blueprint (render.yaml)
- Security & Auth: JWT, Passport, NestJS Throttler, Bcrypt
- API Documentation: Swagger / OpenAPI 3.0
Interested in this Architecture?
Explore the live demo or review the repository on GitHub.