A production-grade digital wallet backend built with FastAPI, PostgreSQL, and Redis.
This is the public engineering documentation for VaultPay — a fintech microservice handling wallets, peer-to-peer transfers, KYC verification, and transaction security. The full private codebase is not public, but this repository documents the architecture, design decisions, and engineering patterns in depth.
Who is this for? Engineers evaluating the codebase, recruiters reviewing technical depth, or anyone curious about how to build a production-grade financial API with FastAPI.
The VaultPay API is currently deployed and publicly accessible. You can explore the endpoints and interact with the service using the live Swagger documentation: https://vaultpay-uvf2.onrender.com/docs
┌─────────────────────────────────────────────────────────────────┐
│ Client / Frontend │
└──────────────────────────┬──────────────────────────────────────┘
│
┌──────────────┴──────────────┐
│ │
┌───────▼────────┐ ┌────────▼────────┐
│ AuthShield │ │ VaultPay │
│ (Port 8000) │ │ (Port 8001) │
│ │◄──────────│ │
│ Auth & Users │ JWT │ Wallets, Txns │
│ JWT issuance │ verify │ KYC, IP Trust │
└───────┬────────┘ └────────┬─────────┘
│ │
┌───────▼────────┐ ┌────────▼─────────┐
│ Redis DB 0 │ │ Redis DB 1 │
│ (AuthShield) │ │ (VaultPay) │
└───────┬────────┘ └──────────────────┘
│ │
┌───────▼────────┐ ┌────────▼─────────┐
│ AuthShield DB │ │ VaultPay DB │
│ (PostgreSQL) │ │ (PostgreSQL 16) │
└────────────────┘ └──────────────────┘
VaultPay and AuthShield are two separate microservices with separate databases. VaultPay validates JWTs locally (fast path) or calls AuthShield's /auth/me endpoint (strict path) — never accessing the AuthShield database directly.
| Feature | Details |
|---|---|
| 🔐 Transaction PIN | bcrypt-hashed 4-digit PIN, 3-attempt lockout, 24h auto-unfreeze |
| 💳 Wallet System | One wallet per user, VPY-XXXXXX human-readable IDs, status state machine |
| 💸 P2P Transfers | 6-step atomic transfers, mid-freeze detection, idempotency keys |
| 🛡️ IP Trust System | Per-IP tracking, 30-min block on new IPs, email confirmation flow |
| 📋 KYC Verification | AES-256 encrypted document storage, SHA-256 hash for duplicate detection |
| 📊 Transaction Limits | Daily/monthly spend limits, elevated after KYC approval |
| 👮 4-Tier RBAC | user → moderator → admin → super_admin across AuthShield + VaultPay |
| 📝 Audit Logging | Append-only audit trail for all privileged operations |
| Layer | Technology |
|---|---|
| API Framework | FastAPI 0.115 + Uvicorn |
| Database | PostgreSQL 16 (asyncpg driver) |
| ORM | SQLAlchemy 2.0 (async) + Alembic migrations |
| Caching / State | Redis 7 (two separate DBs) |
| Auth | JWT (HS256), dual-mode validation |
| Validation | Pydantic v2 |
| Security | bcrypt (PIN), AES-256 (KYC), rate limiting |
| Containerization | Docker + Docker Compose |
| Testing | pytest + pytest-asyncio |
| Auth Microservice | AuthShield (companion service) |
vaultpay/
├── features/
│ ├── wallet/ # Wallet create, balance, status management
│ ├── pin/ # Transaction PIN set/verify/change
│ ├── transactions/ # Send money, history, disputes
│ ├── kyc/ # KYC document submission & review
│ ├── notifications/ # In-app notification management
│ ├── ip_trust/ # IP address trust management
│ ├── admin/ # Moderator + admin operations
│ └── superadmin/ # Super admin system management
├── core/
│ ├── authshield.py # AuthShield client (JWT validation, user lookup)
│ ├── security.py # bcrypt, AES-256, rate limiting utilities
│ └── audit.py # Audit log helper
├── middleware/
│ └── request_id.py # X-Request-ID propagation
├── schemas/
│ └── common.py # StandardResponse[T], PaginatedResponse
├── exceptions.py # Centralized exception hierarchy
├── dependencies.py # FastAPI dependency injection
├── database.py # Async SQLAlchemy session factory
├── redis_client.py # Redis connection pool
├── main.py # App factory, middleware, routers
├── Dockerfile # Multi-stage production build
└── docker-compose.yml # Full stack orchestration
| Document | Description |
|---|---|
| System Architecture | Microservice design, JWT dual-mode auth, RBAC |
| Database Design | ERD, all 8 tables, schema rationale |
| API Reference | All 48+ endpoints across 8 feature groups |
| Security Architecture | PIN, KYC encryption, IP trust, atomic transfers |
| Redis Architecture | Key patterns, DB separation, TTL strategy |
| Feature Flows | Send money, KYC, dispute flows with sequence diagrams |
Annotated, production-ready code samples from the private repo. Every file includes inline comments explaining why each design decision was made.
Architecture & Infrastructure
| File | Pattern Demonstrated |
|---|---|
| exception-hierarchy.py | Centralized typed exception system with HTTP status mapping |
| wallet-model.py | SQLAlchemy 2.0 financial data modeling (Numeric over Float, state machine) |
| auth-middleware.py | Request ID propagation middleware for distributed tracing |
| common-schemas.py | Generic StandardResponse[T] API response envelope |
| docker-compose.yml | Multi-service container orchestration with healthchecks |
| Dockerfile | Multi-stage production build (builder → runtime, non-root user) |
Core Business Logic
| File | Pattern Demonstrated |
|---|---|
| atomic-transfer.py | 6-step P2P transfer: PIN auth → dual-layer idempotency → atomic debit+credit → audit log |
| pin-lockout.py | Brute-force PIN protection: Redis atomic INCR, dual-write durability, auto-freeze, email reset |
| ip-trust-flow.py | IP trust detection: SHA-256 hashing, 30-min confirmation tokens, fail-open Redis strategy |
- RAG-based KYC — LLM-assisted document extraction and verification
- Geo-level IP Detection — Country/city-level IP change detection with policy rules
- Multi-currency Support — INR → multi-currency with real-time FX rates
- WebSocket Notifications — Real-time transaction alerts
- Partial Transaction Reversal — Admin-initiated partial refunds for disputes
Built with precision. Designed for production.