Digital Wallet API 💼💵

A clean, modern banking backend application built using Java, Spring Boot, and PostgreSQL. This project simulates a digital wallet system where users can safely create accounts, check balances, deposit money, and withdraw funds.

The entire project is packaged into a Docker container, allowing it to run instantly on any machine with zero setup.

---

💡 Key Architectural Features (Interview Talking Points)

When building this project, I focused on industry-standard engineering practices rather than just writing code:

• Exact Financial Precision: Used BigDecimal instead of double or float for account balances. This completely prevents standard floating-point rounding errors (like 0.1 + 0.2 = 0.30000000000000004), which is a critical requirement in FinTech.
• Transaction Safety (ACID): Wrapped withdrawal and deposit operations in a @Transactional boundary. This guarantees that if a database save fails halfway through an active process, the entire transaction rolls back automatically—ensuring money is never lost or miscalculated.
• Automated Test Coverage: Implemented isolated unit tests using JUnit 5 and Mockito to test core business logic. Database dependencies were completely mocked to ensure fast, predictable test execution.
• Production-Ready Structure: Separated the application into a clean Three-Tier Architecture (Controllers handle web routes, Services handle business logic validation, and Repositories handle database connectivity).

---

🛠️ Technology Stack

• Language: Java 25 (LTS Release)
• Framework: Spring Boot 3
• Database: PostgreSQL Relational Database
• Data Access: Spring Data JPA / Hibernate ORM
• Testing: JUnit 5, Mockito
• DevOps: Docker / Containerization

---

🚀 How to Run the Project Locally

Prerequisites

• Make sure Docker / Docker Desktop is running on your computer.

Step 1: Spin up the PostgreSQL Database Container

Open your terminal and run this command to start the database in the background:

docker run --name wallet-db -e POSTGRES_USER=admin -e POSTGRES_PASSWORD=secret -e POSTGRES_DB=wallet_db -p 5432:5432 -d postgres

Step 2: Run the Automated Unit Test Suite

Execute the test pipeline to verify business logic constraints and math boundaries:

./mvnw test

Step 3: Compile and Package the Code

Build the standalone executable file using the Maven wrapper script:

chmod +x mvnw
./mvnw clean package -DskipTests

Step 4: Build and Launch the Docker Container

Compile your custom application container image and spin up the complete backend engine:

docker build -t digital-wallet-api .
docker run -p 8080:8080 --name running-wallet-service --link wallet-db:wallet-db digital-wallet-api

---

🧪 Testing the API Endpoints

You can test the running backend endpoints using simple terminal cURL commands (or tools like Postman):

1️⃣ Create a New Wallet Account

curl -X POST http://localhost:8080/api/wallets \
-H "Content-Type: application/json" \
-d '{"ownerName": "Alice", "initialBalance": 500.00}'

2️⃣ Check Account Details & Balance

curl -X GET http://localhost:8080/api/wallets/1

3️⃣ Add a Deposit

curl -X POST "http://localhost:8080/api/wallets/1/deposit?amount=50.00"

4️⃣ Test Low Funds Protection (Edge Case Validation)

Trying to withdraw more money than Alice possesses ($600.00) will be blocked automatically by our validation logic:

curl -X POST "http://localhost:8080/api/wallets/1/withdraw?amount=600.00"