Finance

Centralized financial management module for tracking invoices, payments, balances, and transaction history across all platform operations.

Overview

The Finance module provides the administrative team with a unified view of all financial activity on the platform. It consolidates data from shipments, recharges, and adjustments into a single ledger-like system where operators can review balances, generate invoices, process payments, and export financial reports.

Key Concepts

Concept	Description
Balance	The current financial state of a customer account (available credit)
Transaction	Any financial movement: charge, payment, refund, or adjustment
Invoice	A formal billing document generated from accumulated transactions
Payment	A recorded inflow of funds from a customer (bank transfer, card, etc.)
Adjustment	A manual correction to an account balance (credit or debit)
Billing Cycle	The period over which transactions are accumulated before invoicing

Data Flow

Main Flow: Invoice Generation

Main Flow: Payment Registration

Background Flow: Automatic Billing

Backend Structure

Route Files

backend/routes/
└── finance/
    ├── invoices.js      # Invoice CRUD and generation
    ├── payments.js       # Payment registration and history
    ├── transactions.js   # Transaction listing and filters
    ├── balances.js       # Balance queries and adjustments
    └── reports.js        # Financial report exports

Service Layer

backend/services/
└── finance/
    ├── invoiceService.js       # Invoice generation logic
    ├── paymentService.js       # Payment processing
    ├── transactionService.js   # Transaction recording
    ├── balanceService.js       # Balance calculations
    └── reportService.js        # Report generation (Excel/PDF)

Background Jobs

Job	Queue	Schedule	Description
generateMonthlyInvoices	finance-billing	1st of month, 6:00 AM	Auto-generates invoices for all customers with monthly billing
sendPaymentReminder	finance-notifications	Daily, 9:00 AM	Sends reminders for overdue invoices
reconcileBalances	finance-maintenance	Weekly, Sunday 2:00 AM	Verifies balance consistency across transactions

Validation Schemas

All request payloads are validated with Joi. Schemas are located in:

backend/schemas/
└── finance/
    ├── invoiceSchema.js
    ├── paymentSchema.js
    └── transactionSchema.js

Database

Tables

Table	Purpose
invoices	Invoice headers (customer, dates, totals, status, PDF URL)
invoice_items	Line items within an invoice (description, amount, tax)
payments	Payment records (customer, amount, method, reference)
transactions	Financial ledger: all movements with type, amount, and balance snapshot
customer_balances	Denormalized current balance per customer (updated on each transaction)
billing_configs	Per-customer billing settings (cycle, payment terms, tax rules)

Entity Relationship

Key Fields

transactions

Column	Type	Description
id	INT (PK)	Auto-increment
customer_id	INT (FK)	Reference to customers
type	ENUM	charge, payment, refund, adjustment
amount	DECIMAL(12,2)	Transaction amount (positive = debit, negative = credit)
balance_after	DECIMAL(12,2)	Customer balance snapshot after this transaction
reference_type	VARCHAR	Source entity type (shipment, recharge, manual)
reference_id	INT	Source entity ID
invoice_id	INT (FK, nullable)	NULL until billed
description	VARCHAR	Human-readable description
created_at	DATETIME	Transaction timestamp
created_by	INT (FK)	Admin user who created it

invoices

Column	Type	Description
id	INT (PK)	Auto-increment
customer_id	INT (FK)	Reference to customers
invoice_number	VARCHAR	Sequential invoice number (e.g., INV-2026-001234)
status	ENUM	draft, issued, paid, overdue, cancelled
subtotal	DECIMAL(12,2)	Sum before taxes
tax_amount	DECIMAL(12,2)	Tax amount
total	DECIMAL(12,2)	Final amount
pdf_url	VARCHAR	S3 URL to the generated PDF
issued_at	DATETIME	When the invoice was issued
due_date	DATE	Payment due date
paid_at	DATETIME (nullable)	When fully paid

Key Decisions

Decision	Reasoning	Alternatives Considered
Denormalized customer_balances table	Avoids recalculating balance from all transactions on every query. Updated transactionally with each new transaction.	Calculated view (too slow for dashboards), Redis cache (consistency risk)
balance_after snapshot in transactions	Enables audit trail and debugging without recalculating from history. Critical for financial accuracy.	Only storing deltas (harder to debug, requires full scan for balance at point in time)
Separate invoice_items table	Invoices can contain items from different sources (shipments, adjustments). Flexible line-item structure.	Storing items as JSON in invoices (loses queryability)
Bull queue for billing jobs	Monthly billing can process thousands of customers. Queue provides retry logic, failure handling, and monitoring via Arena.	Cron-only (no retry, no monitoring), external service (unnecessary complexity)
PDF stored in S3	Invoices are legal documents that must be preserved as-is. S3 provides durability and CDN-ready URLs.	Database BLOB (expensive, slow), filesystem (not scalable)

Dependencies

• Internal: Shipments module (generates charges), Customers module (account data), Auth module (admin permissions)
• External: AWS S3 (PDF storage), Mailgun (invoice emails), Excel4node (report generation)

Related Documentation

• API Endpoints — Complete endpoint reference for this module
• UI Screens & Flows — Frontend screens and user interactions
• User Guide — End-user instructions for finance operations