💰 Spring AI Budgeting API

A financial transaction management API built with Spring Boot and Spring AI, integrating Artificial Intelligence capabilities for processing voice commands.

This project was developed as part of the Spring AI final challenge from DIO, using the project presented during the lessons as a foundation and adding my own improvements in implementation, documentation and code quality.

---

🚀 About the Project

The application allows users to create and retrieve financial transactions through a REST API, as well as use Artificial Intelligence to interpret voice commands.

The main AI-powered workflow is:

🎙️ Audio uploaded by the client
        ↓
📝 Speech-to-Text
        ↓
🤖 Spring AI / LLM
        ↓
🔧 Tool Calling
        ↓
💼 Application Use Case
        ↓
🗄️ Data Persistence / Query
        ↓
💬 AI-generated response
        ↓
🔊 Text-to-Speech
        ↓
🎧 MP3 audio returned to the client

The architecture maintains a clear separation between domain, application and infrastructure layers, preventing the AI integration from bypassing the application's business rules.

---

✨ Features

Financial Transactions

• Create new financial transactions.
• Retrieve transactions by category.
• Persist data using Spring Data JPA.
• Validate incoming API data.
• Return appropriate HTTP responses.

Artificial Intelligence

• Speech-to-text transcription.
• Large Language Model integration using Spring AI.
• Function/Tool Calling, allowing the AI to execute real application use cases.
• Text-to-speech synthesis.
• Return the final AI response as an MP3 file.

Improvements Implemented

In addition to the base implementation presented during the challenge, I introduced several improvements to make the project closer to a professional application:

• 📋 Custom project documentation.
• 📝 Structured logging across key operations.
• 🛡️ Request validation using Jakarta Bean Validation.
• ⚠️ Global exception handling structure.
• 📚 API documentation using OpenAPI/Swagger.
• 🧱 Clear separation between application layers.
• 🧪 Application validation through Gradle tests.
• 🐳 MySQL integration using Docker Compose.

---

🏗️ Architecture

The project follows a layered architecture inspired by Clean Architecture and Domain-Driven Design (DDD) principles.

src/main/java/dio/budgeting

├── domain
│   ├── Transaction
│   ├── Category
│   └── TransactionRepository
│
├── application
│   ├── input
│   ├── output
│   ├── PersistTransactionUseCase
│   └── ListTransactionsByCategoryUseCase
│
└── infrastructure
    ├── http
    │   ├── request
    │   ├── response
    │   └── exception
    │
    └── persistence

The application layer contains the business use cases, which can be consumed by both REST endpoints and Spring AI Tool Calling.

---

🛠️ Technologies

• ☕ Java
• 🌱 Spring Boot
• 🤖 Spring AI
• 🌐 Spring Web
• 🗄️ Spring Data JPA
• 🐬 MySQL
• 🐳 Docker / Docker Compose
• 📖 OpenAPI / Swagger
• ✅ Jakarta Bean Validation
• 🧪 JUnit / Spring Boot Test
• 📦 Gradle
• 📝 SLF4J / Logback
• 🧰 Lombok

---

⚙️ Getting Started

Prerequisites

Make sure you have the following installed:

• Java
• Docker Desktop
• Git
• An OpenAI API key for the AI-powered features

1. Clone the repository

git clone https://github.com/PinchiSZ/spring-ai-budgeting.git
cd spring-ai-budgeting/05-spring-ai

2. Configure the API key

Set the following environment variable.

Windows PowerShell

$env:OPENAI_API_KEY="your-api-key-here"

Linux/macOS

export OPENAI_API_KEY="your-api-key-here"

Never add your API key directly to the source code or commit it to Git.

3. Run the application

The project is configured to start MySQL through Docker Compose.

./gradlew bootRun

On Windows:

.\gradlew.bat bootRun

The API will be available at:

http://localhost:8080

---

📚 API Documentation

Once the application is running, the interactive API documentation is available through Swagger UI:

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

Swagger UI can be used to explore and execute the available endpoints directly from the browser.

---

🔌 Main Endpoints

Create a transaction

POST /transactions

Example request:

{
  "description": "Grocery shopping",
  "category": "GROCERIES",
  "amount": 8500
}

Expected response:

201 Created

---

Retrieve transactions by category

GET /transactions/{category}

Example:

GET /transactions/GROCERIES

---

Process an audio command

POST /transactions/ai

The endpoint accepts an audio file through multipart/form-data.

The audio is:

1. Transcribed into text.
2. Sent to the language model.
3. Interpreted by the AI.
4. Routed to the appropriate available Tool.
5. Processed by the application use case.
6. Converted back into audio.
7. Returned as an MP3 file.

This endpoint requires a valid API key and access to the configured AI provider.

---

🧪 Testing

Run the automated tests with:

.\gradlew.bat test

To perform a complete build:

.\gradlew.bat build

During development, the main application flow was also validated through Swagger UI.

The following flows were tested:

• POST /transactions → successfully created a transaction.
• GET /transactions/GROCERIES → successfully retrieved transactions by category.
• POST /transactions/ai → verified the audio processing and AI integration flow.

The AI endpoint requires valid provider credentials. The remaining API functionality can be tested without an AI API key.

---

🐳 Database

The project uses MySQL, running through Docker Compose.

To check whether the database container is running:

docker ps

The container should report a status similar to:

Up ... (healthy)

The application uses the following port mapping:

3307 → 3306

---

📈 What I Learned

Throughout the development of this project, I gained practical experience with:

• Integrating Spring Boot applications with AI models.
• Using Spring AI.
• Speech-to-text and text-to-speech technologies.
• Tool Calling to connect LLMs with real application functionality.
• Building REST APIs.
• Request validation with Jakarta Bean Validation.
• API documentation with OpenAPI/Swagger.
• Implementing application logging with SLF4J.
• Global exception handling.
• Clean Architecture and DDD concepts.
• Data persistence with Spring Data JPA.
• MySQL integration.
• Docker Compose for local development.
• Testing and validation with Gradle.
• Version control and conventional Git commits.
• Improving an existing educational codebase with production-oriented practices.

---

🎓 Credits and Reference

This project was developed from the base project presented during the DIO Spring AI challenge, taught by Thiago Poiani.

The repository contains my own version of the project, based on the implementation presented during the course and extended with additional improvements, including documentation, logging, request validation, exception handling, API documentation and other software engineering practices.

I would like to thank Thiago Poiani and DIO for the course content and the challenge, which provided the foundation for putting the concepts covered in the module into practice.

---

📌 Disclaimer

This project was developed for educational purposes as part of my learning journey in Java, Spring Boot, Spring AI, REST APIs and Artificial Intelligence integration.

The project may continue to evolve as I apply additional software engineering practices and improvements.