LedgerGuard is an enterprise billing and transaction management system designed for multiple companies (tenants) to use the same platform while keeping their data completely isolated.
The system focuses on:
- 🔐 Secure authentication
- 🏢 Multi-tenant architecture
- 💳 Billing and transaction management
- 🔒 Database isolation
- ⚡ Idempotent transactions
- 🔄 Automatic transaction rollback
- 📊 Real-time analytics
- 🔑 Cryptographic security
Enterprise SaaS platforms need strong data isolation and reliable billing systems.
If multiple companies share the same database without proper isolation, one company's data could accidentally become accessible to another company.
Similarly, network failures during financial transactions can cause:
- Duplicate payments
- Incorrect balances
- Incomplete transactions
- Corrupted ledger states
LedgerGuard is designed to solve these problems using isolated databases, Redis locks, MongoDB transactions, JWT authentication, and cryptographic validation.
The main objective of LedgerGuard is to provide a secure billing platform where:
- Multiple companies can use the same application.
- Each company has its own login.
- Each company gets an isolated database.
- Transactions cannot be accidentally duplicated.
- Failed transactions can be rolled back.
- Billing information can be monitored in real time.
- API requests are securely authenticated.
- Usage and billing data can be visualized through dashboards.
LedgerGuard currently supports two demo companies:
- Tenant ID:
company-a - Plan: Enterprise
- Rate Limit: 1000 requests
- Tenant ID:
company-b - Plan: Growth
- Rate Limit: 500 requests
Each company has its own login and accesses only its own data.
LedgerGuard
│
┌──────┴──────┐
│ API Gateway │
└──────┬──────┘
│
┌────────┴────────┐
│ │
Company A Company B
│ │
▼ ▼
Database A Database B
│ │
Transactions Transactions
│ │
▼ ▼
Analytics Analytics
🔐 Authentication
LedgerGuard uses secure authentication to identify the company making an API request.
The authentication flow is:
User
│
▼
Login Page
│
▼
API Gateway
│
▼
Authentication
│
▼
Tenant Identification
│
▼
Company Database
Each company is identified using its tenant information.
JWT-based authentication is used to protect API routes.
💳 Ledger & Transactions
The Ledger module manages financial transactions.
Users can create transactions by providing:
Transaction type
Amount
Description
Supported transaction types include:
Charge
Refund
Example:
Type: Charge
Amount: $100
Description: Monthly Subscription
The transaction is then processed by the backend and stored in the company's isolated database.
🔄 Idempotent Transactions
One of the main features of LedgerGuard is idempotency.
What does idempotency mean?
It means that if the same payment request is accidentally sent multiple times, the system should process it only once.
For example:
Payment Request
│
▼
Request #123
│
▼
Processed
│
▼
$100
If the same request is sent again:
Request #123
│
▼
Already Processed
│
▼
Do NOT charge again
This helps prevent double billing.
🔒 Redis Distributed Locks
Redis is used to prevent multiple requests from modifying the same financial record at the same time.
Example:
Request A ──────┐
│
▼
Redis Lock
│
▼
Process Payment
│
▼
Release Lock
Request B ──────► Wait
This helps protect the ledger from race conditions and duplicate processing.
🗄️ MongoDB Transactions
LedgerGuard uses MongoDB transactions to maintain database consistency.
If all operations succeed:
Transaction
│
├── Update Balance
│
├── Create Ledger Entry
│
└── Save Transaction
│
▼
COMMIT ✅
If something fails:
Transaction
│
├── Update Balance
│
├── Create Ledger Entry
│
└── Network Failure ❌
│
▼
ROLLBACK
This prevents incomplete financial operations.
📊 Dashboard
The React dashboard provides an overview of the company's billing activity.
The dashboard displays:
Current Balance
Total Charges
Total Refunds
Number of Transactions
Recent Transactions
System Health
Hourly Volume
Daily Volume
Example:
┌─────────────────────────────────────────┐
│ DASHBOARD │
├─────────────┬─────────────┬─────────────┤
│ Balance │ Charges │ Refunds │
├─────────────┴─────────────┴─────────────┤
│ │
│ Recent Transactions │
│ │
├─────────────────────────────────────────┤
│ System Health │
│ │
└─────────────────────────────────────────┘
📈 Analytics
The Analytics module provides historical billing information.
It can display:
Revenue over time
Transaction volume
Transaction status
Usage metrics
Historical trends
Users can view information based on:
Hour
Day
Week
The dashboard is designed to provide a clear overview of billing activity.
🔑 Cryptographic Layer
LedgerGuard includes a cryptographic security layer using RSA-256 based key pairs as specified in the project design.
The system uses:
Public keys
Private keys
Secure request validation
The purpose is to strengthen API authentication and payload security.
🏗️ Technology Stack
Backend
Node.js
Express.js
MongoDB
Mongoose
Redis
JWT
bcrypt
Crypto
Frontend
React
Vite
Tailwind CSS
JavaScript / JSX
Chart.js
Infrastructure
📂 Project Structure
ledgerguard/
│
├── backend/
│ │
│ ├── keys/
│ │
│ ├── scripts/
│ │ ├── generateKeys.js
│ │ └── seed.js
│ │
│ ├── src/
│ │ ├── config/
│ │ ├── middleware/
│ │ ├── models/
│ │ ├── routes/
│ │ ├── services/
│ │ ├── utils/
│ │ ├── websocket/
│ │ └── app.js
│ │
│ ├── .env
│ ├── .env.example
│ ├── Dockerfile
│ ├── package.json
│ └── package-lock.json
│
├── frontend/
│ │
│ ├── public/
│ │
│ ├── src/
│ │ ├── components/
│ │ ├── contexts/
│ │ ├── hooks/
│ │ ├── services/
│ │ ├── App.jsx
│ │ ├── index.css
│ │ └── main.jsx
│ │
│ ├── Dockerfile
│ ├── index.html
│ ├── package.json
│ ├── tailwind.config.js
│ └── vite.config.js
│
├── keys/
│
├── scripts/
│
│
└── README.md
⚙️ How the System Works
The complete flow is:
USER
│
▼
LOGIN PAGE
│
▼
JWT AUTHENTICATION
│
▼
API GATEWAY
│
Identify Tenant
│
┌────────┴────────┐
▼ ▼
Company A Company B
│ │
▼ ▼
Database A Database B
│ │
└────────┬────────┘
│
▼
Redis Lock
│
▼
MongoDB Transaction
│
┌────────┴────────┐
│ │
SUCCESS FAILURE
│ │
▼ ▼
COMMIT ROLLBACK
│ │
└────────┬────────┘
▼
DASHBOARD
│
▼
ANALYTICS
🧪 Example Transaction
Suppose Company A creates:
Transaction Type: Charge
Amount: $500
Description: Monthly Subscription
The system performs:
1. Authenticate Company A
↓
2. Identify tenant = company-a
↓
3. Connect to Company A database
↓
4. Acquire Redis lock
↓
5. Check transaction ID
↓
6. Process transaction
↓
7. Update ledger
↓
8. Commit MongoDB transaction
↓
9. Release Redis lock
↓
10. Update dashboard
❌ Failure Scenario
Suppose the network fails while processing the transaction.
Payment Request
↓
Authentication
↓
Redis Lock
↓
MongoDB Transaction
↓
Update Ledger
↓
Network Failure ❌
↓
Rollback
↓
No Partial Transaction
The system should therefore avoid charging the customer twice or leaving the ledger in an inconsistent state.
🌱 Demo Data
The project includes a seed script for creating demo tenants.
The seed data contains:
Company A
Tenant ID: company-a
Plan: Enterprise
Company B
Tenant ID: company-b
Plan: Growth
Run the seed script according to the backend package configuration.
🔒 Security Features
LedgerGuard focuses on several security mechanisms:
JWT authentication
bcrypt password/API-key hashing
Tenant isolation
RSA-based cryptographic validation
Redis distributed locks
MongoDB transactions
Unique transaction identifiers
Environment-based secret management
Protected API routes
⚡ Real-Time Communication
The system is designed to support real-time communication using WebSockets.
This allows the frontend to receive updates without repeatedly refreshing the page.
Example:
Backend
│
│ Transaction Completed
▼
WebSocket
│
▼
React Dashboard
│
▼
Update UI
🧑💻 Development Plan
Week 1 — Dynamic Provisioning
Build API Gateway
Implement JWT authentication
Implement tenant identification
Implement dynamic MongoDB connections
Create separate company databases
Build login and dashboard layout
Week 2 — Idempotent Ledger
Implement Redis distributed locks
Add unique transaction IDs
Implement MongoDB multi-document transactions
Implement transaction rollback
Build Ledger UI
Week 3 — Analytics
Create MongoDB aggregation queries
Calculate usage metrics
Calculate revenue information
Build analytics dashboard
Add charts and historical views
Week 4 — Security & Finalization
Implement cryptographic validation
Improve API security
Add logging
Test tenant isolation
Test transaction failures
Improve dashboard UI
Perform end-to-end testing
🧪 Testing Goals
The following scenarios should be tested:
Tenant Isolation
Company A → Can access Company A data ✅
Company A → Cannot access Company B data ❌
Company B → Can access Company B data ✅
Company B → Cannot access Company A data ❌
Duplicate Transaction
Same Transaction ID
↓
First Request → Processed ✅
Second Request → Rejected/Already Processed ✅
Failed Transaction
Transaction
↓
Network Failure
↓
Rollback
↓
Database remains consistent ✅
🎯 Expected Outcome
At the end of the project, LedgerGuard should provide:
Two separate company login experiences
Secure authentication
Complete tenant isolation
Isolated MongoDB databases
Reliable billing transactions
Duplicate transaction protection
Automatic rollback on transaction failure
Redis-based locking
Real-time dashboard updates
Historical analytics
Secure API endpoints
🚀 Future Improvements
Possible future improvements include:
More tenant/company support
Role-based access control
Admin dashboard
Email notifications
Advanced billing plans
Payment gateway integration
Cloud deployment
Automated backups
Advanced monitoring
Audit logs
More detailed financial reports
📜 Project Information
Project: LedgerGuard
Type: Multi-Tenant SaaS Billing Platform
Architecture: MERN + Redis
Database: MongoDB
Backend: Node.js + Express
Frontend: React
Authentication: JWT
Security: RSA-based cryptography + bcrypt
👨💻 Author
Developed as an academic software engineering project demonstrating:
Full-stack development
Multi-tenant architecture
Database isolation
Secure authentication
Distributed locking
Transaction management
Real-time communication
Data analytics
⭐ LedgerGuard
Secure billing. Isolated tenants. Reliable transactions.