How thomasdacosta/bff-marvel-quarkus works
Project Type and Purpose
• This is a multi-module Java backend-for-frontend (BFF) service built on Quarkus.
• It exposes a character-focused REST API (“bff-marvel-api-character”), reuses shared DTOs and utilities in a common library (“bff-marvel-common”), and includes a local mock of the Marvel API (“marvel-api-mock”) plus AWS LocalStack support for testing SNS notifications.
High-Level File Structure
• Top-level modules (root pom.xml):
• bff-marvel-api-character – the main Quarkus service (inbound/outbound adapters, application core, ports).
• bff-marvel-common – shared client DTOs, controller DTOs, exception handlers, utils.
• marvel-api-mock – a lightweight Quarkus application simulating Marvel API endpoints.
• Support folders:
• aws/localstack – Docker Compose for local AWS SNS.
• .circleci/config.yml – CI pipeline.
• Dockerfiles in each service for JVM, native, legacy jar, micro native builds.
Key Architectural Patterns
• Hexagonal (Ports & Adapters):
• Inbound adapters: JAX-RS controllers (CharacterResource).
• Outbound adapters: REST client implementations (CharacterApiClientImpl) calling Marvel API or mock.
• Application core: service implementations (CharacterServiceImpl) implementing ports.
• Multi-module Maven to separate concerns: BFF logic, common DTOs, mock server.
• Containerization: Docker for each module, localstack for AWS emulation, CircleCI for builds.
Main Components
A. Client (e.g., UI or API consumer)
B. BFF Service (“bff-marvel-api-character”)
1. Inbound Controller Layer (JAX-RS)
2. Mapper Layer (CharacterConverter)
3. Application Core (CharacterServiceImpl)
4. Outbound Port (CharacterApiClientPort)
5. Outbound Adapter (CharacterApiClientImpl)
C. Shared Library (“bff-marvel-common”) – DTOs, exception handlers, utils
D. External Service
• Marvel Public API (or mock for local/dev)
E. AWS LocalStack SNS – for event notifications
F. Infrastructure
• Docker (service containers)
• CircleCI (CI/CD pipeline)
Interactions and Data Flow
1. HTTP GET /characters → BFF Inbound Controller
2. Controller maps request to domain DTO → hands off to Service
3. Service calls the RestClient (CharacterApiClientImpl) via Port
4. RestClient issues HTTP request to:
• Marvel Public API (prod)
• marvel-api-mock (dev/test)
5. Response flows back through converters → controller DTO → HTTP response
6. On certain operations, service publishes SNS event → AWS LocalStack (or real SNS)