Mo-3leem/wallet-transfers-api
Folders and files
| Name | Name | Last commit date | ||
|---|---|---|---|---|
Repository files navigation
    # 💳 Wallet & Transfers API Production-style backend REST API built with **Node.js (Express)** and **PostgreSQL** for secure wallet management and atomic money transfers. This project focuses on real-world financial system engineering concepts — not just CRUD. --- ## 📑 Table of Contents - [Key Highlights](#-key-highlights) - [Features](#-features) - [Performance Optimization](#-performance-optimization) - [Architecture](#-architecture) - [Core Engineering Concepts](#-core-engineering-concepts) - [Tech Stack](#-tech-stack) - [Requirements](#-requirements) - [Run with Docker](#-run-with-docker-recommended) - [Run Without Docker](#-run-without-docker-optional) - [What This Project Demonstrates](#-what-this-project-demonstrates) --- ## 🚀 Key Highlights - ACID-compliant money transfers - Concurrency-safe balance updates - Idempotent transfer API - Append-only ledger system - Soft delete & restore lifecycle - Optimized database indexing - Clean layered architecture - Dockerized development setup - Swagger (OpenAPI) documentation --- ## 🧩 Features ### 1️⃣ Wallet Management - Create wallet - List wallets - Get wallet by ID - Deposit funds - Withdraw funds (with balance validation) - Soft delete wallet (`status = deleted`) - Restore wallet (`status = active`) --- ### 2️⃣ Transfers - Atomic wallet-to-wallet transfers - Row-level locking (`SELECT ... FOR UPDATE`) - Idempotency key enforcement - Transfer status tracking #### Example Request ```http POST /transfers Idempotency-Key: 123e4567-e89b-12d3-a456-426614174000 Content-Type: application/json ``` ```json { "from_wallet_id": "uuid-1", "to_wallet_id": "uuid-2", "amount": 100 } ``` --- ### 3️⃣ Ledger System (Audit Trail) Append-only ledger entries tracking: - DEPOSIT - WITHDRAW - TRANSFER_OUT - TRANSFER_IN Provides: - Full audit trail - Debugging support - Balance reconstruction capability --- ## ⚡ Performance Optimization Indexes added on: - `(from_wallet_id, idempotency_key)` → Fast idempotency validation - `wallet_id` in ledger → Efficient history retrieval - `created_at` → Optimized sorting & pagination Designed to scale with growing data volume. --- ## 🏗 Architecture ``` src/ routes/ → HTTP layer services/ → Business logic db/ → Database & migrations middleware/ → Error handling & validation utils/ → Helpers ``` ### Separation of Concerns - Routes handle HTTP - Services contain core business logic - Database layer ensures data integrity --- ## 🧠 Core Engineering Concepts ### ✅ Atomic Transactions Transfers executed inside DB transaction: ```sql BEGIN; SELECT ... FOR UPDATE; UPDATE wallets ...; INSERT ledger_entries ...; COMMIT; ``` If anything fails → `ROLLBACK`. Guarantees: - No partial money movement - Strong consistency ### ✅ Row-Level Locking Using: ```sql SELECT ... FOR UPDATE; ``` Prevents race conditions and double-spending under concurrent requests. ### ✅ Idempotency Key Each transfer requires: - Idempotency-Key: <UUID> Ensures: - Safe retries - No duplicate transfers - Conflict detection (409) ### ✅ Soft Delete & Restore Instead of removing rows: - DELETE /wallets/:id → sets status = deleted - PATCH /wallets/:id/restore → sets status = active - Maintains referential integrity and ledger consistency. ## 🛠 Tech Stack ### Backend - Node.js - Express.js - PostgreSQL - pg (node-postgres) - UUID - Helmet - Morgan ### DevOps - Docker - Docker Compose - Environment-based config ### Documentation - Swagger (OpenAPI 3) ## 📦 Requirements - Node.js (v18+) - Docker Desktop - Git ## 🐳 Run with Docker (Recommended) ### 1️⃣ Create .env ``` PORT=3000 DATABASE_URL=postgresql://postgres:postgres@db:5432/walletdb ``` ### 2️⃣ Start Containers ```npm run docker:up``` ### 3️⃣ Run Migration ```npm run docker:migrate``` ### 4️⃣ Access API - API → http://localhost:3000 - Health → http://localhost:3000/health - Swagger → http://localhost:3000/docs ### Useful Commands View logs ```npm run docker:logs``` Restart API ```npm run docker:restart``` Stop containers ```npm run docker:down``` Reset database (delete all data) ```npm run docker:reset``` Access PostgreSQL CLI ```npm run docker:psql``` 💻 Run Without Docker (Optional) ```npm install createdb -U postgres walletdb npm run migrate npm run dev ``` Swagger: http://localhost:3000/docs 🎯 What This Project Demonstrates - Production-style backend API design - ACID guarantees in financial systems - Concurrency control using row locks - Idempotent API design - Database indexing strategy - Soft delete lifecycle management - Clean architecture separation - Docker-based workflow