Distributor Management System (DMS)

Overview

A comprehensive Enterprise Resource Planning (ERP) system designed specifically for beverage distribution businesses. The system manages the complete supply chain lifecycle—from supplier procurement through warehouse inventory management to customer sales and delivery—with integrated accounting, payment tracking, and role-based access control.

Problem Solved: Beverage distributors face complex challenges managing multi-warehouse inventory, tracking product batches with expiry dates, handling mixed packaging units (bottles, crates, pallets), managing customer credit limits, and maintaining accurate financial records. This system provides an all-in-one solution that automates inventory adjustments, tracks every transaction, and provides real-time visibility across the entire operation.

Key Features

Inventory Management

• Multi-warehouse tracking with support for warehouses and delivery trucks
• Batch-level inventory with expiry date tracking and FEFO (First Expired, First Out) logic
• Automatic stock adjustments when sales or purchases are processed
• Stock movement tracking with complete audit trail
• Low stock alerts and expiring item notifications
• Mixed crate assembly/disassembly for flexible packaging management

Sales & Customer Management

• Sales order processing with multiple payment methods (cash, credit, bank transfer)
• Route-based pricing for different delivery zones
• Customer credit tracking with outstanding balance management
• Delivery management with status tracking
• Sales verification workflow for quality control
• Credit sales monitoring with aging analysis

Purchase & Supplier Management

• Purchase order creation with supplier tracking
• GRN (Goods Receipt Note) functionality for receiving inventory
• Supplier credit limits and outstanding balance tracking
• Automatic inventory updates when purchases are received
• Purchase history and reporting

Accounting & Financial Management

• Daily transaction recording with automatic journal entries
• Payment history tracking for all transactions
• Financial summaries with revenue, expenses, and profit calculations
• Unpaid items tracking for both sales and purchases
• Audit trail for all financial transactions
• Export capabilities for external accounting software

User Management & Security

• Role-based access control (RBAC) with 10 predefined roles
• Dynamic permission management configurable via admin UI
• JWT-based authentication with secure password hashing (bcrypt)
• Route-level protection preventing unauthorized access
• User activity tracking for accountability

Product Management

• Product hierarchy with parent-child relationships
• Multiple packaging units per product (bottle, crate, pallet, etc.)
• Automatic unit conversions using conversion factors
• Product composition tracking for mixed products
• Preferred display units for consistent reporting

User Interface Design Philosophy

After completing the core business logic, I focused on creating a UI that mirrors the familiar paper-based systems these businesses were already using. The goal was to minimize the learning curve and make the transition seamless. The interface deliberately uses simple, form-based layouts that match their existing workflows—making it feel like a digital version of their current process rather than a completely new system.

This approach significantly reduced training time and user resistance, as employees could immediately understand how to navigate and use the system based on their existing knowledge.

Architecture

High-Level System Design

┌─────────────┐         ┌──────────────┐         ┌──────────────┐
│   Frontend  │ ◄─────► │   Backend    │ ◄─────► │   Database   │
│  (Next.js)  │  REST   │   (NestJS)   │  ORM    │   (MySQL)    │
└─────────────┘   API   └──────────────┘         └──────────────┘

Component Interaction

Frontend → Backend:

• React Query manages API calls with caching and automatic refetching
• Axios handles HTTP requests with JWT token authentication
• Service layer abstracts API endpoints for clean component code

Backend → Database:

• TypeORM provides object-relational mapping with entity relationships
• Database migrations ensure schema consistency across environments
• Transaction support for complex operations (e.g., sales with inventory updates)

Authentication Flow:

1. User logs in with credentials
2. Backend validates and returns JWT token + user data
3. Frontend stores token in localStorage
4. All subsequent requests include token in Authorization header
5. Backend validates token and extracts user role for permission checks

Business Logic Flow (Example: Creating a Sale):

1. Frontend sends sale data to POST /sales endpoint
2. Backend validates data and starts database transaction
3. Sale and SaleItems records created
4. Inventory service automatically deducts stock using FEFO logic
5. Customer outstanding balance updated
6. Payment history recorded if payment made
7. Transaction committed and response returned
8. Frontend updates UI and refetches relevant data

Tech Stack

Backend

• Runtime: Node.js
• Framework: NestJS 11.0
• Language: TypeScript 5.7
• Database: MySQL 3.15
• ORM: TypeORM 0.3
• Authentication: JWT + Passport
• Password Hashing: bcrypt 6.0
• Validation: class-validator 0.14
• API Documentation: Swagger/OpenAPI 11.2
• Task Queue: BullMQ 11.0
• Testing: Jest 30.0

Frontend

• Framework: Next.js 16.0
• Language: TypeScript 5.0
• Styling: TailwindCSS 4.0
• UI Components: ShadCN UI (Radix)
• State Management: Zustand 5.0
• Data Fetching: React Query 5.90
• HTTP Client: Axios 1.13
• Charts: Recharts 3.5
• PDF Export: jsPDF + autotable 3.0
• Icons: Lucide React 0.555
• Notifications: Sonner 2.0

DevOps & Tools

• Database Migrations: SQL-based migration system
• Linting: ESLint 9
• Code Formatting: Prettier 3.4
• Version Control: Git

Data Flow

Complete Transaction Flow

1. USER ACTION (Frontend)
↓
2. API REQUEST (Axios + React Query)
↓
3. AUTHENTICATION (JWT Validation)
↓
4. AUTHORIZATION (Role-based Permission Check)
↓
5. BUSINESS LOGIC (NestJS Service Layer)
↓
6. DATABASE TRANSACTION (TypeORM)
├─ Create/Update Records
├─ Automatic Inventory Adjustments
├─ Update Customer/Supplier Balances
└─ Create Audit Trail Entries
↓
7. RESPONSE (JSON Data)
↓
8. UI UPDATE (React Query Cache Invalidation)

Inventory Flow Example

Sale Transaction:

Sale Created → Inventory Service Called → FEFO Logic Applied 
→ Stock Deducted from Oldest Batch → Stock Audit Log Created 
→ Customer Balance Updated → Payment History Recorded

Purchase Transaction:

Purchase Created → Marked as Received (GRN) → Inventory Service Called 
→ Stock Added to Warehouse → New Batch Created → Supplier Balance Updated

Notable Implementations

1. FEFO (First Expired, First Out) Inventory Logic

The system automatically deducts stock from batches with the nearest expiry date, ensuring product freshness and minimizing waste. This is critical for beverage distribution where product shelf life matters.

2. Automatic Inventory Synchronization

Sales and purchases automatically trigger inventory adjustments within database transactions, ensuring data consistency. If any step fails, the entire transaction rolls back, preventing inventory discrepancies.

3. Dynamic Role-Based Access Control

Unlike hardcoded permissions, the system stores role permissions in the database, allowing administrators to customize access rights through a visual UI without code changes. Changes take effect immediately across all users.

4. Multi-Unit Packaging System

Products can have multiple packaging units (e.g., 1 Crate = 24 Bottles) with automatic conversions. The system tracks inventory at the most granular level while allowing sales and purchases in any unit.

5. Mixed Crate Management

Supports assembling mixed crates from individual bottles and disassembling them back, with automatic inventory adjustments for all components. This is essential for beverage distributors offering variety packs.

6. Route-Based Pricing

Different customers can have different prices for the same product based on their delivery route, accommodating zone-based pricing strategies common in distribution businesses.

7. Comprehensive Audit Trail

Every stock movement, payment, and transaction is logged with timestamps, user information, and reasons. This provides complete traceability for compliance and dispute resolution.

8. Transaction Date Tracking

All sales and purchases record both creation date and transaction date, allowing accurate financial reporting for backdated transactions and period-end adjustments.

9. Credit Management with Aging Analysis

Tracks outstanding balances for customers and suppliers with aging reports (30/60/90 days), helping businesses manage cash flow and identify collection issues.

10. Real-Time Dashboard Analytics

Aggregates data across sales, inventory, and accounting to provide instant insights into business performance, including revenue trends, top products, and low stock alerts.

Use Case

Target Users

• Beverage distributors (soft drinks, water, beer, wine)
• Wholesale distribution companies with multi-warehouse operations
• FMCG distributors managing perishable goods with expiry dates
• Small to medium-sized distribution businesses needing affordable ERP solutions

Real-World Application

Scenario: A beverage distribution company operates 3 warehouses and 5 delivery trucks, serving 200+ retail customers across different zones.

Daily Operations:

1. Morning: Warehouse manager checks low stock alerts and creates purchase orders for suppliers
2. Throughout Day: Sales reps create orders on tablets/phones, system automatically deducts inventory
3. Delivery: Drivers receive delivery lists, update status as deliveries complete
4. Evening: Accountant reviews daily transactions, records payments received
5. End of Day: Manager reviews dashboard for sales performance and inventory status

Benefits:

• Inventory Accuracy: Real-time stock levels prevent overselling and stockouts
• Financial Control: Automatic accounting entries eliminate manual bookkeeping errors
• Credit Management: System alerts when customers exceed credit limits
• Compliance: Complete audit trail for tax authorities and auditors
• Efficiency: Reduces manual data entry by 80%, freeing staff for customer service
• Visibility: Management can monitor operations from anywhere via web interface

Key Business Metrics Tracked

• Daily/monthly revenue and profit margins
• Inventory turnover rates
• Customer payment patterns and aging
• Product performance and sales trends
• Warehouse efficiency and stock levels
• Delivery completion rates
• Outstanding receivables and payables

Performance Considerations

• Database indexing on foreign keys and frequently queried fields
• React Query caching reduces unnecessary API calls
• Lazy loading of components and routes
• Optimistic UI updates for better user experience
• Transaction batching for complex operations

Scalability

• Modular architecture allows easy addition of new features
• Database migrations support schema evolution
• Stateless backend enables horizontal scaling
• Configurable via environment variables for different deployments

---

Conclusion

This Distributor Management System demonstrates a full-stack enterprise application with complex business logic, real-time data synchronization, and robust security. It showcases proficiency in modern web technologies, database design, API development, and user experience design. The system solves real business problems faced by distribution companies, providing measurable value through automation, accuracy, and visibility.

Key Takeaways:

• Full-stack TypeScript development (NestJS + Next.js)
• Complex domain modeling with proper entity relationships
• Transaction management for data consistency
• Role-based security with dynamic permissions
• Real-time UI updates with optimistic rendering
• Production-ready code with proper error handling and validation
• User-centered design approach for seamless adoption