🏦 ACP-BANK

ACP-BANK is a full-stack, microservices-based digital banking platform that simulates real-world banking workflows for both Bank Staff (Bank Side) and Users (User Side).

• On the Bank Side, staff authenticate with branch credentials, create customer accounts, and manage deposits.
• On the User Side, customers can only register if their account exists in the bank’s database (just like SBI YONO). Once registered, they can log in, check balances, make payments, and view transaction history.

Built with Node.js/Express microservices, React (Vite) frontend, Kafka for event-driven messaging, Docker for containerization, JWT authentication, and MongoDB for persistence.

---

📑 Table of Contents

• Description
• Workflows
• Features
• Tech Stack
• Project Structure
• Architecture
• Microservices Architecture
• Bank Side Flow
• User Side Flow
• Installation
• Usage
• API Reference
• Testing
• Contributing
• Roadmap
• Known Issues
• License
• Contact

---

🏦 Description

ACP-BANK replicates how modern banks operate with a Bank-First Workflow:

1. Bank Staff create customer accounts (with required details + initial deposit).
2. Users can only register after their account exists in the Bank DB.
3. Secure transactions, payments, and notifications are enabled for verified users.

This design ensures realism and security, just like actual digital banking systems (e.g., SBI YONO).

---

🔄 Workflows

Bank Side (Staff Portal)

• Staff login with Branch Name + Branch Secret Code.
• Create new customer accounts (requires initial deposit).
• Validate and manage account details.
• Deposit money into accounts during account creation or later.

User Side (Customer App)

• Users can only register if their Account Number exists in Bank DB.
• Registration requires OTP verification (via SMS).
• Login with JWT authentication.
• Users can:
  • View account balance.
  • Deposit, withdraw, transfer money.
  • View transaction history/statements.
  • Receive real-time notifications (via Kafka + SMS/Email).

---

✨ Features

🔑 Bank Side (Staff Portal)

• Branch Authentication: Staff login with branch credentials.
• Account Creation: Staff create new customer accounts with required details.
• Initial Deposit: Accounts are only activated after deposit is made.
• Internal Operations: Staff can update or validate accounts.

👤 User Side (Customer App)

• Secure Registration: Users can register only if account exists in DB.
• OTP Verification: OTP sent via Twilio SMS.
• Login with JWT: Secure token-based authentication.
• Banking Services: Check balance, transfer money, withdraw, deposit.
• Transaction Statements: View all past transactions.
• Real-Time Notifications: Kafka publishes events → Notification Service sends SMS/Email.

🔒 Security

• JWT Tokens for secure sessions.
• OTP Verification for account registration/login.
• AES Encryption for sensitive payment data.

---

🛠 Tech Stack

• Frontend: React + Vite
• Backend: Node.js, Express
• Messaging: Apache Kafka
• Database: MongoDB
• Auth/Security: JWT, OTP (via Twilio SMS), AES encryption
• Containerization: Docker + Docker Compose
• Tooling: ESLint, npm

---

📂 Project Structure

Backend/
  BankServer/             # Bank-side services
    accountServer/        # Account lifecycle (create, update, delete)
    bankServerGateway/    # Branch/staff authentication
  GatewayServer/          # API Gateway (entrypoint)
  PaymentServer/          # Payment service (deposit, withdraw, transfer)
  Notification/           # Kafka consumer → notifications (SMS/Email)
  UserServer/             # User microservice (registration, login, profiles)

Frontend/                 # React + Vite frontend

---

🏗 Architecture

Simplified Flow

   [ Client / Frontend ]
        /         \
 [User Side]   [Bank Side]
       |           |
       v           v
 [ API Gateway (3000) ]
      /   |   \
     v    v    v
 [User] [Account] [Payment]
              |
              v
         Publishes Events
              |
              v
         [Kafka Bus]
              |
              v
  [Notification Service]
       (SMS / Email Alerts)

---

🧩 Microservices Architecture

ACP-BANK follows a microservices-based architecture where each service is independent, modular, and communicates over APIs and events.

🔹 Why Microservices?

• Independent deployment and scaling of services.
• Easier maintenance (change one service without breaking all).
• Fault isolation (if Payment fails, Auth still works).
• Event-driven scalability using Kafka.

🔹 Role of Kafka

• Acts as the message bus between services.
• Payment transactions publish events → consumed by Notification Service.
• Enables asynchronous communication and event-driven design.

🔹 Role of Docker

• Each service runs in its own Docker container.
• Kafka and Zookeeper run as containers.
• Future: A docker-compose.yml can orchestrate all services together.

🔹 Security Mechanisms

1. JWT Authentication → Secure login sessions for users.
2. OTP Verification (via Twilio) → Prevents unauthorized user registration.
3. AES Encryption → Protects sensitive data (payments, account numbers).
4. Service-Level Authentication → Bank staff must verify with branch credentials.

🔹 End-to-End Flow

1. Bank Staff create account → record saved in Account Service.
2. User registers → User Service checks Account DB → OTP verification.
3. User logs in → JWT issued.
4. Payment Service handles deposit/withdraw/transfer.
5. Payment Service publishes events to Kafka Bus.
6. Notification Service consumes events → sends SMS/Email.
7. All services run in Docker → can scale independently.

---

🏛 Bank Side Flow

1. Staff authenticate via Branch Name + Secret Code.
2. Staff create new accounts by entering customer details.
3. Staff add initial deposit → only then account is activated.
4. User can now register on the customer app.

Endpoints (BankServerGateway)

• POST /api/v1/bank/verify → Verify branch session.
• POST /api/v1/accounts/newaccount → Create a new account with deposit.
• GET /api/v1/bank/health → Service health check.

---

👤 User Side Flow

1. User registers → system checks if AccountNo exists in Bank DB.
2. OTP sent via Twilio → user verifies OTP.
3. On successful verification → account activated for user.
4. User logs in → receives JWT token.
5. User can now perform banking operations.

Endpoints (UserServer)

• POST /api/v1/users/register → Register (validates account number).
• POST /api/v1/users/verify → Verify OTP.
• POST /api/v1/users/login → Login.
• GET /api/v1/users/userinfo/:accountNo → Get user info.

---

                      ┌──────────────────┐
                      │    BANK STAFF    │
                      └───────┬──────────┘
                              │
                      ┌───────▼──────────┐
                      │  GATEWAY SERVER  │
                      └───────┬──────────┘
                              │
         ┌────────────────────┼─────────────────────┐
         │                    │                     │

┌─────────▼────────┐ ┌───────▼──────────┐ ┌─────▼──────────┐ │ BANK SERVER │ │ USER SERVER │ │ PAYMENT SERVER │ │ (Staff Auth, Ops) │ │ (Reg/Login) │ │ (Txn Handling) │ └─────────┬────────┘ └────────┬─────────┘ └────────┬────────┘ │ │ │ ┌─────────▼────────┐ ┌─────────▼─────────┐ ┌───────▼─────────┐ │ BANK GATEWAY SRV │ │ CUSTOMER DB │ │ PAYMENT DB │ └─────────┬────────┘ └───────────────────┘ └────────┬────────┘ │ │ ┌─────────▼────────┐ │ │ ACCOUNT SERVER │ │ └─────────┬────────┘ │ │ │ ┌─────────▼────────┐ │ │ BANK DB │ │ └──────────────────┘ │ │ ┌───────▼───────┐ │ KAFKA BUS │ └───────┬───────┘ │ ┌──────────▼──────────┐ │ NOTIFICATION SERVER │ │ (SMS / Email Alerts)│ └─────────────────────┘

⚙️ Installation

Prerequisites

• Node.js ≥ 18
• MongoDB (local/cloud)
• Docker + Docker Compose (for Kafka)
• Git

Steps

# Clone repo
git clone <repo-url>
cd ACP-BANK

# Install dependencies (each service)
cd Backend/UserServer && npm install
cd Backend/AccountServer && npm install
cd Backend/PaymentServer && npm install
cd Backend/Notification && npm install
cd Backend/GatewayServer && npm install
cd Frontend && npm install

# Start Kafka
cd Backend/PaymentServer
docker-compose up -d

# Start services (separate terminals)
npm start

# Start frontend
cd Frontend
npm run dev

Visit → http://localhost:5173

---

🚀 Usage

Bank Side Example (cURL)

# Staff login
curl -X POST http://localhost:3000/api/v1/bank/verify \
 -d '{"branch":"KolkataMain","branchSecret":"secure123"}'

# Create new account (with deposit)
curl -X POST http://localhost:3000/api/v1/accounts/newaccount \
 -d '{"name":"Arijit","phone":"+911234567890","deposit":5000}'

User Side Example (cURL)

# Register user (account must exist in DB)
curl -X POST http://localhost:3000/api/v1/users/register \
 -d '{"accountNo":"ACC001","email":"a@b.com","password":"pass","phone":"+15551234567"}'

# Verify OTP
curl -X POST http://localhost:3000/api/v1/users/verify \
 -d '{"email":"a@b.com","otp":"123456"}'

# Login
curl -X POST http://localhost:3000/api/v1/users/login \
 -d '{"email":"a@b.com","password":"pass"}'

---

📡 API Reference

🏛 Bank Side (BankServerGateway)

• POST /api/v1/bank/verify → Branch authentication
• POST /api/v1/accounts/newaccount → Create account
• GET /api/v1/bank/health → Health check

👤 User Side (UserServer)

• POST /api/v1/users/register → Register user
• POST /api/v1/users/verify → Verify OTP
• POST /api/v1/users/login → Login
• GET /api/v1/users/userinfo/:accountNo → User info

💸 Payment Server

• POST /api/v1/payments/deposite → Deposit
• PUT /api/v1/payments/withdraw → Withdraw
• PUT /api/v1/payments/pay/:sender → Transfer funds
• PUT /api/v1/payments/status/:id → Update status
• GET /api/v1/payments/paymentinfo/:accountNo → Payment info
• GET /api/v1/payments/transaction → All transactions

🔔 Notification Server

• Kafka consumer → listens for transaction events.
• Sends SMS/Email alerts.
• No public REST endpoints.

---

🧪 Testing

• Unit + integration tests per service.

• Suggested:

  • Mock Kafka in tests.
  • Use test MongoDB instance.
  • Add validation + controller tests.

---

🤝 Contributing

• Branch naming: feature/<name>, fix/<name>, chore/<name>

• Flow:

  1. Fork & create feature branch
  2. Keep changes scoped per service
  3. Update docs if needed
  4. Ensure lint passes
  5. Open PR

• Commit style: Conventional Commits (feat:, fix:, chore:)

---

🗺 Roadmap

• Centralized Docker Compose for all services.
• CI/CD with GitHub Actions.
• Observability (logging, tracing, metrics).
• Role-based access (admin, customer).
• Audit logging for compliance.

---

⚠️ Known Issues

• Kafka must be running for payment + notifications.
• No global docker-compose.yml yet.
• Limited request validation.
• Twilio trial SMS → only verified numbers.

---

📜 License

MIT License.

---

📬 Contact

Maintainer: Arojit Paul Email: paulajitchnadra11111@gnail.com GitHub: Arojit45