Backend Ledger System

A secure and scalable Ledger Management System built using Node.js, Express.js, MongoDB, and Mongoose that supports account-based transactions, immutable ledger entries, idempotent payments, JWT authentication, email notifications, and ACID-compliant database transactions.

This project simulates how modern payment systems and banking backends maintain transaction consistency and prevent duplicate processing.

---

Features

Authentication & Authorization

• JWT-based Authentication
• Protected Routes using Middleware
• System User Authorization
• Secure Password Hashing using bcryptjs
• Cookie & Bearer Token Support
• Logout using Token Blacklisting

User Management

• User Registration
• User Login
• Secure Password Storage
• Email Validation

Account Management

• Create Accounts
• Active/Inactive Account Status
• Account Ownership
• Dynamic Balance Calculation

Transaction System

• Money Transfer between Accounts
• Idempotency Key Support
• Duplicate Transaction Prevention
• Transaction Status Tracking

Supported Transaction Status:

• PENDING
• COMPLETED
• FAILED
• REVERSED

Immutable Ledger System

Every transaction creates immutable ledger entries:

• DEBIT Entry → Sender Account
• CREDIT Entry → Receiver Account

Ledger entries cannot be modified or deleted, ensuring auditability and financial consistency.

MongoDB Transactions

Uses MongoDB Sessions & Transactions to ensure:

• Atomic Operations
• Data Consistency
• Rollback on Failure
• Safe Multi-document Transactions

Email Notifications

Automatic email notifications for:

• User Registration
• Successful Transactions

Dynamic Balance Calculation

Account balance is derived from ledger entries:

Balance = Total Credits - Total Debits

No direct balance mutation ensures higher reliability.

---

Tech Stack

Backend

• Node.js
• Express.js

Database

• MongoDB Atlas
• Mongoose

Authentication

• JSON Web Token (JWT)

Security

• bcryptjs

Email Service

• Nodemailer
• Google OAuth2

Environment Management

• dotenv

---

Project Structure

project3/
│── src/
│   ├── controllers/
│   │   ├── account.controller.js
│   │   ├── auth.controller.js
│   │   └── transaction.controller.js
│   │
│   ├── db/
│   │   └── db.js
│   │
│   ├── middleware/
│   │   └── auth.middleware.js
│   │
│   ├── models/
│   │   ├── account.model.js
│   │   ├── blackList.model.js
│   │   ├── ledger.model.js
│   │   ├── transaction.model.js
│   │   └── user.model.js
│   │
│   ├── routes/
│   │   ├── account.routes.js
│   │   ├── auth.routes.js
│   │   └── transaction.routes.js
│   │
│   ├── services/
│   │   └── email.service.js
│   │
│   └── app.js
│
│── .env
│── .gitignore
│── package.json
│── package-lock.json
│── server.js

---

Installation & Setup

1. Clone Repository

git clone <your-repository-url>
cd project3

2. Install Dependencies

npm install

3. Create Environment Variables

Create a .env file in the root directory:

PORT=3000

MONGODB_URI=your_mongodb_connection_string

JWT_SECRET=your_secret_key

EMAIL_USER=your_email@gmail.com
CLIENT_ID=your_google_client_id
CLIENT_SECRET=your_google_client_secret
REFRESH_TOKEN=your_refresh_token

4. Run Server

Development Mode:

npm run dev

Production Mode:

npm start

---

API Endpoints

Authentication Routes

Register User

POST /api/auth/register

Request Body:

{
    "name": "Abhishek",
    "email": "abhishek@test.com",
    "password": "123456"
}

Login User

POST /api/auth/login

Request Body:

{
    "email": "abhishek@test.com",
    "password": "123456"
}

Logout User

POST /api/auth/logout

---

Account Routes

Create Account

POST /api/account/create

Get Account Balance

GET /api/account/balance/:accountId

---

Transaction Routes

Create Transaction

POST /api/transaction/create

Request Body:

{
    "fromAccount": "account_id",
    "toAccount": "account_id",
    "amount": 2000,
    "idempotencyKey": "unique-id"
}

---

Idempotency Example

If a request is sent multiple times using the same:

"idempotencyKey"

Then:

Already Processed

{
    "message": "Transaction already processed."
}

Transaction in Progress

{
    "message": "Transaction is still processing."
}

This prevents duplicate money transfer issues.

---

Security Features

• JWT Authentication
• Password Hashing using bcrypt
• Token Blacklisting
• Immutable Ledger Entries
• Transaction Rollback
• Authorization Middleware
• Environment Variable Protection
• Input Validation

---

Testing

You can test APIs using:

• Postman
• Thunder Client
• Hoppscotch

---

Future Improvements

• Transaction History
• Pagination
• Rate Limiting
• Redis Queue for Async Processing
• Transaction Reversal APIs
• Admin Dashboard
• Docker Deployment
• Swagger API Documentation

---

Author

Abhishek Goyal

---

License

This project is licensed under the MIT License.