💸 Wallet System

A backend REST API built with Spring Boot for managing user wallets, bets, transactions, and balances.

---

✨ Features

• User wallet management (balance, transaction history)
• Bet placing & result processing
• Transactional integrity (ACID via @Transactional)
• Global exception handling for consistent error responses
• DTO <-> Entity mapping with MapStruct
• Bean Validation for request data
• Logging with SLF4J
• API documentation with Swagger/OpenAPI
• Layered & SOLID architecture

---

🏗️ Architecture

The project follows a layered, SOLID-compliant architecture:

• Controller Layer: Handles HTTP requests and responses.
• Service Layer: Business logic, transactional control, logging.
• Repository Layer: Data access using Spring Data JPA.
• DTOs: Data Transfer Objects expose only necessary fields.
• Mappers: MapStruct for automatic DTO <-> Entity conversion.
• Exception Handling: Centralized with @ControllerAdvice.
• Config Management: All sensitive data via .env or environment variables.

---

🚀 Technologies

• Java 17
• Spring Boot 3
• Spring Data JPA (Hibernate)
• PostgreSQL
• Maven
• Swagger (OpenAPI)
• Lombok
• MapStruct
• SLF4J

---

🛠️ Getting Started

✅ Prerequisites

• Java 17+
• PostgreSQL
• Maven

⚙️ Setup Instructions

1. Start PostgreSQL and create a database:

   createdb wallet_db

2. Update your database credentials in src/main/resources/application.properties:

   spring.datasource.url=jdbc:postgresql://localhost:5432/wallet_db
   spring.datasource.username=your_username
   spring.datasource.password=your_password
   

3. The application reads sensitive values from environment variables. Example for local run:

   export $(cat .env | xargs)
   mvn spring-boot:run

4. Run the application:

   -If you have Maven installed globally: mvn spring-boot:run

   -Or using the Maven Wrapper: ./mvnw spring-boot:run

🔁 Usage Flow

-Create New User

-Place New Bet

-Process Bet Result

-List All Transactions

-Get User Information

-View Betting History

-Check Wallet Balance

🛡️ Error Handling Example

All exceptions are handled globally and return a consistent error format:

{
    "error": "Not Found",
    "message": "User not found with id: ",
    "timestamp": "2025-06-08T14:14:18.909037",
    "status": 404
}

📬 Postman Collection

You can import the Postman collection below to test all API endpoints:

➡️ wallet-system.postman_collection.json

📘 Example API Call

➕ Create User

POST /api/users

{
"username": "JaneDoe",
"balance": 95000
}

Response:

{
    "data": {
        "id": 1,
        "username": "JaneDoe",
        "balance": 95000,
        "createdAt": "2025-06-06T20:34:47.397127"
    },
    "message": "Success",
    "success": true
}

📄 API Documentation

Visit Swagger UI for full API documentation:

👉 http://localhost:8080/swagger-ui/index.html

📄 License

This project is licensed under the MIT license.