DigitalBank

A production-ready digital banking REST API built with FastAPI, featuring multi-currency wallets, balance management, and financial operations with a clean modular architecture.

Features

• Authentication — JWT-based auth with asymmetric RSA keys (RS256), access/refresh token rotation, and token revocation
• User Management — registration, profile updates, account closure, and role-based access (User / Admin)
• Wallets — create debit and credit wallets secured by PIN, block/unblock, soft close
• Multi-currency Balances — regular and foreign balance accounts per wallet, freeze/unfreeze support
• Financial Operations — deposit, withdrawal, and inter-wallet transfer with fee calculation
• Transaction History — full audit trail with status tracking (pending / success / failed) and type classification
• Admin Panel — dedicated admin endpoints for user, wallet, balance, and transaction management

Tech Stack

Layer	Technology
Framework	FastAPI 0.136
ASGI Server	Uvicorn / Gunicorn
ORM	SQLAlchemy 2.0 (async)
Database	PostgreSQL 16
Migrations	Alembic
Auth	PyJWT + bcrypt + RSA keys
Validation	Pydantic v2
DI Container	Dishka
Logging	Loguru
Linting	Ruff + Pyright
Runtime	Python 3.14

Project Structure

app/
├── api/v1/              # Router registry + health check
├── common/
│   ├── decorators.py    # Debug logging decorator
│   ├── enums/           # StrEnums for users, wallets, balances, transactions
│   └── exceptions/      # Custom exceptions + global exception handler
├── core/settings/
│   ├── jwt.py           # JWT RSA key settings
│   ├── logger.py        # Loguru configuration
│   └── server/          # Uvicorn/Gunicorn adapter + config
├── database/
│   ├── models/          # SQLAlchemy ORM models (User, Wallet, Balance, Transaction, Refresh)
│   └── config.py        # Async engine + session factory
├── di/
│   └── container.py     # Dishka DI container wiring
├── modules/
│   ├── auth/            # Login, logout, refresh
│   ├── users/           # CRUD + block/unblock
│   ├── wallets/         # Debit/credit wallets + PIN
│   ├── balances/        # Regular/foreign balances
│   ├── operations/      # Deposit, withdraw, transfer, exchange
│   └── transactions/    # Transaction read access (admin)
├── unit_of_work/
│   └── uow.py           # Async UoW for session/commit management
└── main.py

Each module follows a consistent internal layout: api/v1/ → contracts/ (schemas, DTOs, responses) → service/ (use cases, guards, utils) → repository/ (queries, commands).

Getting Started

Prerequisites

• Docker & Docker Compose
• openssl (for generating RSA keys)

1. Clone the repository

git clone https://github.com/wittiden/DigitalBank.git
cd DigitalBank

2. Generate RSA keys

cd certs

# Access token keys
openssl genrsa -out access-private.pem 2048
openssl rsa -in access-private.pem -pubout -out access-public.pem

# Refresh token keys
openssl genrsa -out refresh-private.pem 2048
openssl rsa -in refresh-private.pem -pubout -out refresh-public.pem

⚠️ Never commit *-private.pem files to version control.

3. Configure environment

cp .env.example .env

Fill in .env:

SERVER_HOST=
SERVER_PORT=
SERVER_WORKERS=
SERVER_WORKER_CLASS=uvicorn.workers.UvicornWorker
SERVER_RELOAD=False

DB_USER=postgres
DB_PASS=
DB_HOST=db
DB_PORT=
DB_NAME=digital_bank_dev
MODE=DEV

PGADMIN_EMAIL=
PGADMIN_PASS=
PGADMIN_PORT=

ACCESS_ALGORITHM=
ACCESS_PUBLIC_KEY_PATH=certs/access-public.pem
ACCESS_PRIVATE_KEY_PATH=certs/access-private.pem
ACCESS_TOKEN_EXPIRE_MINUTES=

REFRESH_ALGORITHM=
REFRESH_PUBLIC_KEY_PATH=certs/refresh-public.pem
REFRESH_PRIVATE_KEY_PATH=certs/refresh-private.pem
REFRESH_TOKEN_EXPIRE_DAYS=
REFRESH_TOKEN_VERSION=

4. Run the application

# Start the app + database
docker compose up -d
# Start the app + database + pgadmin
docker compose --profile pgadmin up -d


# Apply migrations (first time or after schema changes)
docker compose --profile migrations up

API Overview

All endpoints are versioned under /api/v1.

Auth — /api/v1/auth

Method	Endpoint	Description
POST	/login	Authenticate and receive tokens
POST	/logout	Revoke current session
POST	/refresh	Rotate access/refresh tokens

Users — /api/v1/users

Method	Endpoint	Description
POST	/	Register a new user
PATCH	/me	Update own profile
DELETE	/me	Close own account

Admin: Users — /api/v1/admin/users

Method	Endpoint	Description
POST	/	Create admin account
GET	/{user_id}	Get user by ID
GET	/	List all users
DELETE	/{user_id}	Delete user
PATCH	/block/{user_id}	Block user
PATCH	/unblock/{user_id}	Unblock user

Wallets — /api/v1/wallets

Method	Endpoint	Description
POST	/credit	Open a credit wallet
POST	/debit	Open a debit wallet
PATCH	/	Update wallet settings
DELETE	/me	Close own wallet (requires PIN)

Admin: Wallets — /api/v1/admin/wallets

Method	Endpoint	Description
DELETE	/{wallet_id}	Force-delete wallet
PATCH	/block/{wallet_id}	Block wallet
PATCH	/unblock/{wallet_id}	Unblock wallet

Balances — /api/v1/balances

Method	Endpoint	Description
POST	/regular	Create a regular balance
POST	/foreign	Create a foreign currency balance
DELETE	/	Close balance (requires wallet PIN)

Admin: Balances — /api/v1/admin/balances

Method	Endpoint	Description
PATCH	/freeze/{balance_id}	Freeze balance
PATCH	/unfreeze/{balance_id}	Unfreeze balance
DELETE	/{balance_id}	Delete balance

Operations — /api/v1/operations

Method	Endpoint	Description
POST	/deposit	Deposit funds into a balance
POST	/withdraw	Withdraw funds from a balance
POST	/transfer	Transfer between wallets

Admin: Transactions — /api/v1/admin/transactions

Method	Endpoint	Description
GET	/	List all transactions (paginated)
GET	/{transaction_id}	Get transaction by ID

Interactive docs available at http://localhost:{SERVER_PORT}/docs.

Development

Install dependencies locally

pip install -r requirements.txt

Run locally (without Docker)

python -m app.main --uvicorn
# or
python -m app.main --gunicorn

Linting & type checking

ruff check .
ruff format .
pyright

Pre-commit hooks

pre-commit install
pre-commit run --all-files

Tests are organized into tests/unit/, tests/integration/, and tests/e2e/.

Data Model

User
 └── Wallet (debit | credit)
      └── Balance (regular | foreign)
           └── Transaction (deposit | withdraw | transfer | exchange)
                           status: pending | success | failed

• User can have multiple wallets of different types.
• Wallet holds multiple currency balances and is protected by a hashed PIN.
• Balance tracks an amount in a specific currency and can be frozen by an admin.
• Transaction records every financial movement with full metadata (fee, rate, timestamps, status).