🏦 NexaBank — Enterprise Core Banking System

GitHub: https://github.com/sufyanwithcode/nexabank Author: @sufyanwithcode

A production-grade, three-tier core banking application built with React, Node.js/Express, PostgreSQL, and Redis — fully Dockerized and CI/CD-ready.

---

📐 Architecture Overview

┌─────────────────────────────────────────────────────────┐
│                    CLIENT BROWSER                        │
└─────────────────────┬───────────────────────────────────┘
                       │ HTTP/HTTPS
┌─────────────────────▼───────────────────────────────────┐
│              TIER 1 — PRESENTATION                        │
│        Nginx Reverse Proxy (Port 80/443)                 │
│                       │                                   │
│         ┌─────────────▼──────────────┐                   │
│         │   React.js Frontend (SPA)  │                   │
│         │   React Router v6          │                   │
│         │   Zustand State Mgmt       │                   │
│         │   Axios HTTP Client        │                   │
│         └────────────────────────────┘                   │
└─────────────────────┬───────────────────────────────────┘
                       │ REST API /api/*
┌─────────────────────▼───────────────────────────────────┐
│              TIER 2 — APPLICATION                         │
│         Node.js 20 + Express.js API                      │
│         ├── JWT Auth (Access + Refresh tokens)           │
│         ├── Bcrypt password hashing (12 rounds)          │
│         ├── Express Rate Limiting                        │
│         ├── Helmet security headers                      │
│         ├── Input validation (express-validator)         │
│         └── Winston structured logging                   │
└────────────┬──────────────────────┬──────────────────────┘
             │ SQL (pg pool)         │ Cache (ioredis)
┌────────────▼──────────┐  ┌────────▼───────────────────┐
│  TIER 3 — DATABASE    │  │  TIER 3 — CACHE            │
│  PostgreSQL 16        │  │  Redis 7                   │
│  ├── Users            │  │  ├── Session cache          │
│  ├── Accounts         │  │  ├── Token blacklist        │
│  ├── Transactions     │  │  └── User/account cache     │
│  ├── Loans            │  └────────────────────────────┘
│  └── Audit Logs       │
└───────────────────────┘

---

🚀 Technology Stack

Layer	Technology	Version	Purpose
Frontend	React.js	18.x	SPA UI
Frontend State	Zustand	4.x	Global state
Frontend Router	React Router	6.x	Client routing
Frontend HTTP	Axios	1.x	API calls
Backend	Node.js + Express	20 + 4.x	REST API
Authentication	JWT + bcryptjs	—	Auth & security
Database	PostgreSQL	16	Primary data store
Cache/Sessions	Redis	7	Caching, token blacklist
Reverse Proxy	Nginx	1.25	Load balancing, SSL
Containerization	Docker + Compose	24+	Deployment
CI/CD	GitHub Actions	—	Automation
Registry	GitHub Container Registry	—	Docker images

---

📁 Project Structure

nexabank/
├── .github/
│   └── workflows/
│       └── ci-cd.yml          # GitHub Actions pipeline
├── backend/
│   ├── src/
│   │   ├── config/            # DB, Redis, Logger
│   │   ├── controllers/       # Auth, Account, Transaction, Loan, Admin
│   │   ├── middleware/        # Auth, Error, Validation
│   │   └── routes/            # All API routes
│   ├── Dockerfile
│   └── package.json
├── frontend/
│   ├── src/
│   │   ├── components/        # React UI components
│   │   ├── services/          # Axios API service
│   │   └── utils/             # Zustand store
│   ├── Dockerfile
│   └── package.json
├── database/
│   └── migrations/
│       └── 001_initial_schema.sql
├── nginx/
│   └── nginx.conf
├── scripts/
│   ├── deploy.sh              # Linux deployment
│   └── backup.sh              # DB backup
├── docker-compose.yml
└── .env.example

---

⚡ Quick Start (Local Development)

Prerequisites

• Docker Desktop 24+ or Docker Engine + Docker Compose plugin
• Git

1. Clone

git clone https://github.com/sufyanwithcode/nexabank.git
cd nexabank

2. Configure Environment

cp .env.example .env
# Edit .env with your preferred passwords/secrets
nano .env

3. Launch All Services

docker compose up -d --build

4. Access

Service	URL	Credentials
Frontend	http://localhost:3000	Register or use admin
Backend API	http://localhost:5000/api/health	—
PgAdmin	http://localhost:5050	admin@nexabank.com / Admin@2024
Via Nginx	http://localhost	Routes to both

Default admin: admin@nexabank.com / Admin@2024

---

🐧 Linux Server Deployment

Option A — Automated Script (Recommended)

# 1. SSH into your Ubuntu 22.04+ server
ssh user@your-server-ip

# 2. Download and run deploy script
curl -fsSL https://raw.githubusercontent.com/sufyanwithcode/nexabank/main/scripts/deploy.sh \
  -o deploy.sh

# 3. Fresh install
sudo bash deploy.sh --fresh

# 4. Update (after pushing new code)
sudo bash deploy.sh --update

# 5. Rollback
sudo bash deploy.sh --rollback

Option B — Manual Step-by-Step

# 1. Install Docker on Ubuntu 22.04
sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
  | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
  https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" \
  | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo systemctl enable --now docker

# 2. Clone repository
sudo git clone https://github.com/sufyanwithcode/nexabank.git /opt/nexabank
cd /opt/nexabank

# 3. Configure environment
sudo cp .env.example .env
sudo nano .env   # Change passwords & secrets!

# 4. Deploy
sudo docker compose up -d --build

# 5. Verify
docker compose ps
curl http://localhost:5000/api/health

---

🔄 CI/CD Pipeline

The GitHub Actions pipeline (.github/workflows/ci-cd.yml) runs on every push to main:

Push to main
     │
     ▼
┌─────────────────┐    ┌─────────────────┐
│  test-backend   │    │  test-frontend  │
│  ─────────────  │    │  ─────────────  │
│  npm ci         │    │  npm ci         │
│  npm run lint   │    │  npm run build  │
│  npm test       │    └────────┬────────┘
│  (Postgres +    │             │
│   Redis svc)    │             │
└────────┬────────┘             │
         └──────────┬───────────┘
                    ▼
         ┌────────────────────┐
         │   build-push       │
         │   ───────────────  │
         │  docker build      │
         │  push to ghcr.io   │
         │  /sufyanwithcode/  │
         │  nexabank-backend  │
         │  nexabank-frontend │
         └─────────┬──────────┘
                   ▼
         ┌────────────────────┐
         │   deploy           │
         │   ───────────────  │
         │  SSH to server     │
         │  git pull          │
         │  docker compose    │
         │  up -d             │
         └────────────────────┘

Required GitHub Secrets

Go to: https://github.com/sufyanwithcode/nexabank/settings/secrets/actions

Secret	Description
DEPLOY_HOST	Your server IP or hostname
DEPLOY_USER	SSH username (e.g., ubuntu)
DEPLOY_SSH_KEY	Private SSH key (cat ~/.ssh/id_rsa)
REACT_APP_API_URL	Your production API URL

---

🗄️ Database Schema

Key Tables

users        -- Customers, tellers, admins
accounts     -- Checking, savings, FD, business
transactions -- All financial movements (ACID)
loans        -- Loan applications and repayments
audit_logs   -- Full audit trail

Database Management

# Connect to PostgreSQL
docker compose exec postgres psql -U nexabank_user -d nexabank

# Manual backup
docker compose exec -T postgres pg_dump -U nexabank_user nexabank > backup.sql

# Restore backup
docker compose exec -T postgres psql -U nexabank_user nexabank < backup.sql

# Automated backup (add to crontab)
sudo crontab -e
# Add: 0 2 * * * /opt/nexabank/scripts/backup.sh

---

🔌 API Endpoints

Method	Endpoint	Auth	Description
POST	/api/auth/register	—	Register new user
POST	/api/auth/login	—	Login
POST	/api/auth/logout	✅	Logout (blacklists token)
POST	/api/auth/refresh	—	Refresh access token
GET	/api/auth/me	✅	Current user + accounts
GET	/api/accounts	✅	List accounts
POST	/api/accounts	✅	Open new account
POST	/api/accounts/:id/deposit	✅	Deposit funds
POST	/api/accounts/:id/withdraw	✅	Withdraw funds
GET	/api/transactions	✅	Transaction history
POST	/api/transactions/transfer	✅	Transfer between accounts
GET	/api/loans	✅	My loans
POST	/api/loans/apply	✅	Apply for loan
POST	/api/loans/:id/repay	✅	Make loan payment
GET	/api/admin/stats	🔒 Admin	Dashboard stats
GET	/api/admin/users	🔒 Admin	All users
GET	/api/admin/loans/pending	🔒 Admin	Pending loans
PATCH	/api/admin/loans/:id/approve	🔒 Admin	Approve/reject loan

---

🔧 Useful Docker Commands

# View running services
docker compose ps

# View logs
docker compose logs -f backend
docker compose logs -f frontend
docker compose logs -f postgres

# Restart a service
docker compose restart backend

# Scale backend (load balancing)
docker compose up -d --scale backend=3

# Stop all
docker compose down

# Stop + remove volumes (⚠️ destroys data)
docker compose down -v

---

🔒 Security Features

• JWT Access tokens (15 min TTL) + Refresh tokens (7 days)
• Token blacklisting via Redis on logout
• Bcrypt password hashing (12 rounds)
• Helmet.js security headers
• Rate limiting: 200 req/15min global, 10 req/15min auth
• Row-level locking for concurrent transactions (ACID)
• Non-root Docker containers
• CORS configuration
• Input validation on all endpoints

---

📞 Support

• GitHub Issues: https://github.com/sufyanwithcode/nexabank/issues
• Author: @sufyanwithcode