# thomasdacosta/bff-marvel-quarkus architecture

> Architecture diagram of the GitHub repository thomasdacosta/bff-marvel-quarkus, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/thomasdacosta/bff-marvel-quarkus
- Repository: https://github.com/thomasdacosta/bff-marvel-quarkus

## Overview

##### 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)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Modules and Libraries
    subgraph "BFF Service (bff-marvel-api-character)" 
        classDef microservice fill:#add8e6,stroke:#333,stroke-width:1px
        CharacterResource["CharacterResource\n(JAX-RS Controller)"]:::microservice
        CharacterConverter["CharacterConverter\n(Mapper)"]:::microservice
        CharacterServiceImpl["CharacterServiceImpl\n(Application Core)"]:::microservice
        CharacterApiClientPort["CharacterApiClientPort\n(Outbound Port)"]:::microservice
        CharacterApiClientImpl["CharacterApiClientImpl\n(Outbound Adapter)"]:::microservice
    end

    subgraph "Common Library (bff-marvel-common)"
        classDef common fill:#90ee90,stroke:#333,stroke-width:1px
        SharedClientDTOs["Client DTOs"]:::common
        SharedControllerDTOs["Controller DTOs"]:::common
        SharedExceptionHandlers["Exception Handlers"]:::common
        SharedUtilities["Utilities"]:::common
    end

    subgraph "Mock API (marvel-api-mock)"
        classDef microservice fill:#add8e6,stroke:#333,stroke-width:1px
        MockApiResource["MockApiResource\n(Controller)"]:::microservice
    end

    %% External Systems
    classDef external fill:#ffa500,stroke:#333,stroke-width:1px
    Client["Client"]:::external
    MarvelAPI["Marvel Public API"]:::external
    SNS(("AWS SNS\n(LocalStack)")):::external

    %% Interactions
    Client -->|"HTTP/JSON"| CharacterResource
    CharacterResource -->|"maps DTO"| CharacterConverter
    CharacterConverter -->|"to service"| CharacterServiceImpl
    CharacterServiceImpl -->|"calls port"| CharacterApiClientPort
    CharacterApiClientPort -->|"interface"| CharacterApiClientImpl
    CharacterApiClientImpl -->|"HTTP/JSON"| MarvelAPI
    CharacterApiClientImpl -->|"HTTP/JSON (dev)"| MockApiResource
    CharacterServiceImpl -->|"SNS publish"| SNS

    %% Shared Library Usage
    CharacterConverter --> SharedControllerDTOs
    CharacterConverter --> SharedClientDTOs
    CharacterServiceImpl --> SharedUtilities
    CharacterResource --> SharedExceptionHandlers

    %% Click Events
    click CharacterResource "https://github.com/thomasdacosta/bff-marvel-quarkus/blob/main/bff-marvel-api-character/src/main/java/br/com/marvel/adapters/inbound/controller/CharacterResource.java"
    click CharacterConverter "https://github.com/thomasdacosta/bff-marvel-quarkus/blob/main/bff-marvel-api-character/src/main/java/br/com/marvel/adapters/inbound/mapper/CharacterConverter.java"
    click CharacterServiceImpl "https://github.com/thomasdacosta/bff-marvel-quarkus/blob/main/bff-marvel-api-character/src/main/java/br/com/marvel/application/core/service/CharacterServiceImpl.java"
    click CharacterApiClientPort "https://github.com/thomasdacosta/bff-marvel-quarkus/blob/main/bff-marvel-api-character/src/main/java/br/com/marvel/application/ports/out/CharacterApiClientPort.java"
    click CharacterApiClientImpl "https://github.com/thomasdacosta/bff-marvel-quarkus/blob/main/bff-marvel-api-character/src/main/java/br/com/marvel/adapters/outbound/restclient/CharacterApiClientImpl.java"
    click SharedClientDTOs "https://github.com/thomasdacosta/bff-marvel-quarkus/tree/main/bff-marvel-common/src/main/java/br/com/marvel/client/dto/"
    click SharedControllerDTOs "https://github.com/thomasdacosta/bff-marvel-quarkus/tree/main/bff-marvel-common/src/main/java/br/com/marvel/controller/dto/characters/"
    click SharedExceptionHandlers "https://github.com/thomasdacosta/bff-marvel-quarkus/tree/main/bff-marvel-common/src/main/java/br/com/marvel/controller/exception/handler/"
    click SharedUtilities "https://github.com/thomasdacosta/bff-marvel-quarkus/tree/main/bff-marvel-common/src/main/java/br/com/marvel/utils/"
    click MockApiResource "https://github.com/thomasdacosta/bff-marvel-quarkus/blob/main/marvel-api-mock/src/main/java/br/com/marvel/controller/MockApiResource.java"
    click SNS "https://github.com/thomasdacosta/bff-marvel-quarkus/blob/main/aws/localstack/docker-compose.yml"
    click CharacterResource "https://github.com/thomasdacosta/bff-marvel-quarkus/blob/main/bff-marvel-api-character/src/main/resources/application-localstack.properties"
    click DockerBFF "https://github.com/thomasdacosta/bff-marvel-quarkus/blob/main/bff-marvel-api-character/src/main/docker/Dockerfile.jvm"
    click DockerMock "https://github.com/thomasdacosta/bff-marvel-quarkus/blob/main/marvel-api-mock/src/main/docker/Dockerfile.jvm"
    click CICD "https://github.com/thomasdacosta/bff-marvel-quarkus/blob/main/.circleci/config.yml"
```
