Skip to content

Devanshu11976/Banking-System

BranchesTags

Repository files navigation

banner

🏦 Banking System

A Lightweight Demo Banking System with AI-Assisted Fraud Detection

Java React Groq AI Maven License


Raw Java. Real concurrency. AI fraud checks. No heavy frameworks.

📌 What Is This?

Banking System is a self-contained, demo-grade banking backend built entirely on raw Java 17 — no Spring Boot, no Hibernate, no application server. It pairs a hand-crafted HttpServer REST API with a React + Vite frontend and an AI-assisted fraud detection pipeline that gracefully degrades to deterministic heuristics when no API key is configured.

It's designed to be easy to run, easy to read, and genuinely interesting to demonstrate.

🚀 What Makes This Stand Out

✦ Framework-Light Java Backend

Most banking demos use Spring Boot and hide everything behind annotations. This project exposes the raw mechanics:

  • com.sun.net.httpserver.HttpServer — manual route registration, manual request parsing, manual response writing
  • Manual JSON handling via org.json — no ObjectMapper magic, every field read and validated explicitly
  • Zero reflection, zero dependency injection — you can trace every call from HTTP request to in-memory state update

This is the difference between using a framework and understanding what it does.

✦ AI + Heuristic Hybrid Fraud Pipeline

The fraud detection system is production-inspired in its design:

  • When GROQ_API_KEY is set → sends transaction context to an LLM for intelligent fraud scoring
  • When the API is unavailable or unconfigured → falls back automatically to a deterministic heuristic engine (amount thresholds, velocity checks, account age)
  • APIs always respond — the fraud check never blocks or crashes a transaction
  • This is exactly how real fraud systems work: AI augments, heuristics guarantee

✦ Atomic Transactions with Per-Account Locks

Deposits, withdrawals, and transfers are processed with:

  • Per-account ReentrantLock — prevents race conditions on concurrent balance updates
  • Atomic in-memory state using ConcurrentHashMap — no lost updates
  • Rollback logic on transfer failure — if credit fails after debit, the debit is reversed

No database, no JPA — just Java concurrency primitives used correctly.

✦ Self-Contained, Zero-Friction Demo

  • Single JSON jar (lib/json-20231013.jar) — the only external dependency
  • run.bat / start-all.bat — one command to start backend + frontend together
  • scripts/api-test.ps1 — PowerShell smoke test suite to demo all endpoints immediately
  • Built frontend in frontend/dist — no npm install needed to see the UI

✦ Clean Secrets Practice

  • API key read from environment variable GROQ_API_KEY or config/local.properties
  • config/local.properties.example provided — fill and rename, never commit
  • .gitignore pre-configured to exclude all local secrets

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                    React Frontend (Vite)                    │
│              frontend/src  ·  frontend/dist                 │
│         Accounts UI · Transaction Forms · Dashboard         │
└──────────────────────────┬──────────────────────────────────┘
                           │  HTTP :8080
┌──────────────────────────▼──────────────────────────────────┐
│              Java HttpServer (Raw, No Framework)            │
│                    Manual Route Dispatch                    │
└───┬──────────────────────┬──────────────────────┬───────────┘
    │                      │                      │
┌───▼──────────┐  ┌────────▼───────┐  ┌───────────▼─────────┐
│  Account     │  │  Transaction   │  │  Fraud Detection    │
│  Handler     │  │  Handler       │  │  Handler            │
│              │  │                │  │                     │
│ create/list  │  │ deposit        │  │  AI call (Groq)     │
│ get/update   │  │ withdraw       │  │  ↓ on failure       │
│              │  │ transfer       │  │  Heuristic fallback │
└───┬──────────┘  └────────┬───────┘  └───────────┬─────────┘
    │                      │                       │
    └──────────────────────┼───────────────────────┘
                           │
┌──────────────────────────▼──────────────────────────────────┐
│                  In-Memory Data Store                       │
│   ConcurrentHashMap<AccountId, Account>                     │
│   ConcurrentHashMap<AccountId, ReentrantLock>               │
│   List<Transaction> (synchronized)                          │
└─────────────────────────────────────────────────────────────┘

📁 Project Structure

banking_system-main/
├── pom.xml                              ← Maven build config
├── run.bat                              ← Start backend only
├── start-all.bat                        ← Start backend + frontend together
├── lib/
│   └── json-20231013.jar               ← Only external dependency
├── config/
│   └── local.properties.example        ← Copy → local.properties, add API key
├── scripts/
│   └── api-test.ps1                    ← PowerShell smoke tests for all endpoints
├── src/main/java/com/banking/
│   ├── Main.java                       ← Entry point, server bootstrap
│   ├── handlers/
│   │   ├── AccountHandler.java         ← CRUD for accounts
│   │   ├── TransactionHandler.java     ← Deposit / withdraw / transfer
│   │   └── FraudHandler.java          ← Fraud check endpoint
│   ├── services/
│   │   ├── AccountService.java         ← Account business logic + locking
│   │   ├── TransactionService.java     ← Atomic transaction processing
│   │   └── FraudDetectionService.java  ← AI call + heuristic fallback
│   ├── models/
│   │   ├── Account.java
│   │   └── Transaction.java
│   ├── tools/
│   │   └── TestRunner.java             ← Internal demo test harness
│   └── utils/
│       └── ApiConfig.java             ← Reads GROQ_API_KEY from env/config
└── frontend/
    ├── src/                            ← React + Vite source
    └── dist/                           ← Pre-built assets (serve immediately)

⚙️ Setup & Running

Prerequisites

  • Java 17+
  • Maven 3.8+ (or use the javac/java scripts directly)
  • Node.js 18+ (only if rebuilding the frontend)

Option 1 — Start Everything (Recommended)

start-all.bat

Starts the Java backend on :8080 and serves the React frontend. Open http://localhost:5173 for the UI.

Option 2 — Backend Only

run.bat

API available at http://localhost:8080

Option 3 — Maven

mvn clean package
java -jar target/banking-system.jar

Option 4 — Frontend Dev Server (live reload)

cd frontend
npm install
npm run dev

🔑 AI Fraud Detection Setup

# Set your Groq API key (free at console.groq.com)
export GROQ_API_KEY=your_key_here        # Linux / macOS
$env:GROQ_API_KEY="your_key_here"        # Windows PowerShell

Or create config/local.properties from the example file:

GROQ_API_KEY=your_key_here

If no key is set, the system automatically falls back to heuristic fraud detection. All endpoints still work.

🔌 API Reference

Accounts

Method Endpoint Description
POST /api/accounts Create a new account
GET /api/accounts List all accounts
GET /api/accounts/{id} Get account by ID
PUT /api/accounts/{id} Update account details

Transactions

Method Endpoint Description
POST /api/transactions/deposit Deposit funds
POST /api/transactions/withdraw Withdraw funds
POST /api/transactions/transfer Transfer between accounts
GET /api/transactions/{accountId} Get transaction history

Fraud

Method Endpoint Description
POST /api/fraud/check Run fraud analysis on a transaction

Example: Create Account

curl -X POST http://localhost:8080/api/accounts \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Devanshu Sharma",
    "email": "devanshu@example.com",
    "initialBalance": 5000.00
  }'

Response:

{
  "accountId": "ACC-2024-001",
  "name": "Devanshu Sharma",
  "email": "devanshu@example.com",
  "balance": 5000.00,
  "status": "ACTIVE",
  "createdAt": "2024-12-01T10:30:00Z"
}

Example: Transfer with Fraud Check

curl -X POST http://localhost:8080/api/transactions/transfer \
  -H "Content-Type: application/json" \
  -d '{
    "fromAccountId": "ACC-2024-001",
    "toAccountId": "ACC-2024-002",
    "amount": 1500.00,
    "description": "Rent payment"
  }'

Response:

{
  "transactionId": "TXN-8842",
  "status": "COMPLETED",
  "amount": 1500.00,
  "fraudCheck": {
    "score": 12,
    "verdict": "SAFE",
    "method": "AI",
    "reasoning": "Routine transfer within normal velocity range."
  }
}

Example: Fraud Check

curl -X POST http://localhost:8080/api/fraud/check \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "ACC-2024-001",
    "amount": 49999.00,
    "type": "WITHDRAWAL"
  }'

Response:

{
  "score": 87,
  "verdict": "SUSPICIOUS",
  "method": "HEURISTIC",
  "flags": ["amount_exceeds_threshold", "unusual_velocity"],
  "recommendation": "HOLD_FOR_REVIEW"
}

🧪 Running Tests

PowerShell Smoke Tests (all endpoints)

cd scripts
.\api-test.ps1

Runs a full create → deposit → transfer → fraud-check sequence and prints pass/fail for each step.

Internal Test Harness

# After starting the server:
mvn exec:java -Dexec.mainClass="com.banking.tools.TestRunner"

🛡️ Fraud Detection — How It Works

Transaction Received
       │
       ▼
┌─────────────────────────────────┐
│    Is GROQ_API_KEY configured?  │
└──────────┬──────────────────────┘
           │ Yes                    No
           ▼                        ▼
  ┌─────────────────┐    ┌──────────────────────────┐
  │   Groq LLM API  │    │   Heuristic Engine       │
  │                 │    │   • Amount threshold      │
  │  Transaction +  │    │   • Velocity check        │
  │  account context│    │   • Account age check     │
  │  → fraud score  │    │   • Round number flag     │
  └────────┬────────┘    └─────────────┬────────────┘
           │ Failure/timeout           │
           └───────────────┬───────────┘
                           │
                           ▼
                  Fraud Score (0–100)
                  Verdict: SAFE / SUSPICIOUS / BLOCKED
                  Always returned — never null

🧩 Tech Stack

Layer Technology
Language Java 17
HTTP Server com.sun.net.httpserver (zero framework)
JSON org.json (single jar)
Concurrency ConcurrentHashMap + ReentrantLock
AI Fraud Groq API via Java HttpClient
Frontend React + Vite
Styling Tailwind utility classes + custom CSS
Build Maven + javac/java scripts
Testing Internal TestRunner + PowerShell smoke tests

🏆 Why This Project Stands Out

Feature Typical Banking Demo This Project
Backend framework Spring Boot Raw HttpServer
Fraud detection None / mock AI + heuristic fallback
Concurrency Framework-managed Per-account ReentrantLock
Transfer atomicity Not handled Debit + credit + rollback
External dependencies 20+ jars One JSON jar
Run complexity mvn spring-boot:run magic You see exactly what starts
Secrets management application.properties Env var + .gitignore
Frontend None or template React + Vite, pre-built

🔮 Recommended Next Steps

  • Add JUnit 5 tests wired into mvn test
  • Introduce H2/SQLite for persistence demos
  • Add JWT authentication layer
  • GitHub Actions CI — build + smoke test on push
  • Upgrade Vite/esbuild to clear npm audit warnings

📄 License

MIT License — see LICENSE for details.

Built with raw Java and a genuine love for systems programming.

No frameworks were harmed in the making of this project.

⚡ A DevSan Original

Two engineers. One system. Zero frameworks.

DS   SJ

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages