API Car with FIPE integration (Hexagonal Architecture)

Version DDD and Clean Architecture on api-car-manager-with-fipe

API register vehicle indexed by brand and model with external client app price search.

---

🧱 Hexagonal Architecture (Ports & Adapters)

📘 Concept

Hexagonal (or Ports and Adapters) architecture isolates the core business logic from external systems. It makes the application independent of frameworks, databases, or delivery mechanisms.

---

🧩 Diagram (ASCII in Markdown)

               +-----------------------------+
               |        Incoming Adapters     |
               |   (Controllers, CLI, APIs)   |
               +-------------▲---------------+
                             │
                             │ Port (Input)
                             │
               +-------------┴---------------+
               |        Application Core     |
               |   (Use Cases / Domain Logic) |
               +-------------▲---------------+
                             │
                             │ Port (Output)
                             │
               +-------------┴---------------+
               |       Outgoing Adapters      |
               | (DB, REST API, Message Bus)  |
               +-----------------------------+

---

⚙️ Layers Explained

Layer	Description	Examples
Core (Domain + Use Cases)	Contains pure business logic. No external dependencies.	Domain models, services
Incoming Adapter	Translates external input into commands for the core.	REST controller, CLI, GraphQL
Outgoing Adapter	Implements interfaces to external systems defined by the core.	Repository, HTTP client, Message queue

---

🔁 Flow Example

1. Incoming adapter (API Controller) receives a request.
2. It calls a use case defined in the core (via an input port).
3. The use case uses an output port (interface) to interact with a repository adapter.
4. The repository adapter talks to the database.
5. The core remains isolated — easily testable, replaceable, and reusable.

---

🌟 Benefits

✅ Testability: Core can be tested without DB or frameworks.
✅ Replaceable Adapters: Switch from REST → gRPC, or SQL → NoSQL easily.
✅ Maintainability: Business logic stays clean and stable.
✅ Independence: Frameworks and tools are secondary — not dictating your design.

---

Operation Functional Flow (part by part)

1. Receive request for create Vehicle by POST Rest entrypoint
2. Validate database schema constraints, as: UK, Marca and Modelo
3. Produce Event for schedule creation
4. Consume Event and convert to Object
5. Request External Client Demo FIPE getting the vehicle FIPE price
6. When has External client Integration Error: send to DLQ
7. Convert vehicle Price value to number
8. Save vehicle on database

Stack

API:

• Java 11: Language Programming version 11
• Spring Boot: Java Injection Framework
• Spring Web: Embedded Web Server (Apache Tomcat)
• Spring JPA: ORM Hibernate
• OpenFeign: Web Client
• RabbitMQ: Async Queue Messaging
• Actuator: Health check
• Flyway: Manage Database Migration Versioning
• Netflix Ribbon: Client Side Load Balancer (Manage OpenFeign Client)
• Jackson ObjectMapper: Library for mapper objects java.
• PostgreSQL: Database SQL
• PostgreSQL Driver: Configure connection with PostgreSQL Database
• Lombok: Java Code Style Improvements

Tests:

• Wiremock: Mock Web client Server
• H2: Light weight Embedded SQL Database
• RestAssured: Testing BDD REST API
• H2 Driver: Configure connection with H2 Database

Running App

Requirements

• JDK Java 11
• Docker / Docker Compose

./gradlew build --parallel --x test
docker build --tag=car-api:latest .
docker-compose up

Open App

• Health Check
• Swagger
• Database Adminer
• RabbitMQ Manager

Example Vehicle Request:
Endpoint: POST /api/v1/veiculos

Payload:

{
  "placa": "NEW-4321",
  "marcaId": 21,
  "modeloId": 473,
  "precoAnuncio": 1000000,
  "ano": 2011
}

Database Credentials:

• Database Adminer

System: PosgreSQL
Server: db
Username: 123456789
Password: 123456789
Database: postgres

RabbitMQ Credentials:

• RabbitMQ Manager

Username: guest
Password: guest

Schema

Vehicle Creation Flow

Credits:

Sham Vinicius Fiorin
By Dryve