# lue93/api-fx architecture

> Architecture diagram of the GitHub repository lue93/api-fx, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lue93/api-fx
- Repository: https://github.com/lue93/api-fx

## Overview

FX is a Spring API for converting an amount between fiat currencies using current rates from Wise. The documented request workflow enters through the exchange controller, is coordinated by a use case, obtains a rate and calculates the converted amount, then returns the result. The sampled proxy service checks an in-memory cache and fetches missing or stale rates through the Wise client. The use-case implementation and some integration wiring were not sampled, so those links are based on the documented workflow and omitted where ownership is uncertain.

Main entry points: [`src/main/java/br/com/lue93/fx/adapters/controllers/FiatExchangeController.java`](https://github.com/lue93/api-fx/blob/main/src/main/java/br/com/lue93/fx/adapters/controllers/FiatExchangeController.java) (Exchange endpoint), [`src/main/java/br/com/lue93/fx/application/usecase/fiat/exchange/FiatExcxhangeUseCase.java`](https://github.com/lue93/api-fx/blob/main/src/main/java/br/com/lue93/fx/application/usecase/fiat/exchange/FiatExcxhangeUseCase.java) (Exchange use case), [`src/main/java/br/com/lue93/fx/application/services/rate/ProxyRateService.java`](https://github.com/lue93/api-fx/blob/main/src/main/java/br/com/lue93/fx/application/services/rate/ProxyRateService.java) (Cached rate lookup), [`src/main/java/br/com/lue93/fx/application/services/rate/WiseRateService.java`](https://github.com/lue93/api-fx/blob/main/src/main/java/br/com/lue93/fx/application/services/rate/WiseRateService.java) (Wise rate service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API boundary"]
  node_controller["Exchange endpoint"]
  node_errors["REST error mapping"]
  node_openapi["API documentation"]
end

subgraph group_app["Application flow"]
  node_usecase["Exchange use case"]
  node_fiatservice["Amount conversion"]
end

subgraph group_domain["Currency domain"]
  node_fiatcontract["Exchange contract"]
  node_fiatdata["Exchange data<br/>[FiatInputData.java]"]
  node_fiatresult["Converted amount"]
  node_symbols["Currency symbols<br/>[Symbol.java]"]
  node_rate["Rate model<br/>[Rate.java]"]
  node_rateinput["Rate request<br/>[RateInput.java]"]
  node_rateoutput["Rate result<br/>[RateOutPut.java]"]
  node_ratecontract["Rate contract<br/>[RateService.java]"]
end

subgraph group_integration["Rate integration"]
  node_proxy["Cached rate lookup"]
  node_cache["In-memory rate cache<br/>[RateCache.java]"]
  node_wise["Wise rate service"]
  node_feign["Wise HTTP client"]
end

node_client(("API caller"))
node_wiseapi(("Wise service"))

node_client -->|"submits exchange"| node_controller
node_controller -->|"invokes"| node_usecase
node_usecase -->|"calculates amount"| node_fiatservice
node_usecase -->|"requests rate"| node_proxy
node_fiatservice -->|"returns result"| node_fiatresult
node_proxy -->|"checks and updates"| node_cache
node_proxy -->|"fetches on miss or expiry"| node_wise
node_wise -->|"requests rates"| node_feign
node_feign -->|"fetches rate"| node_wiseapi
node_wise -->|"builds result"| node_rateoutput
node_feign -->|"receives rates"| node_rate
node_controller -.->|"errors handled by"| node_errors

click node_controller "https://github.com/lue93/api-fx/blob/main/src/main/java/br/com/lue93/fx/adapters/controllers/FiatExchangeController.java"
click node_errors "https://github.com/lue93/api-fx/blob/main/src/main/java/br/com/lue93/fx/infra/spring/exception/RestControllerExceptionHandler.java"
click node_openapi "https://github.com/lue93/api-fx/blob/main/src/main/java/br/com/lue93/fx/infra/spring/doc/SpringDocConfig.java"
click node_usecase "https://github.com/lue93/api-fx/blob/main/src/main/java/br/com/lue93/fx/application/usecase/fiat/exchange/FiatExcxhangeUseCase.java"
click node_fiatservice "https://github.com/lue93/api-fx/blob/main/src/main/java/br/com/lue93/fx/application/services/fiat/FiatExchangeServiceWiseRates.java"
click node_fiatcontract "https://github.com/lue93/api-fx/blob/main/src/main/java/br/com/lue93/fx/domain/fiat/services/FiatExchangeService.java"
click node_fiatdata "https://github.com/lue93/api-fx/blob/main/src/main/java/br/com/lue93/fx/domain/fiat/vo/FiatInputData.java"
click node_fiatresult "https://github.com/lue93/api-fx/blob/main/src/main/java/br/com/lue93/fx/domain/fiat/vo/FiatOutputData.java"
click node_symbols "https://github.com/lue93/api-fx/blob/main/src/main/java/br/com/lue93/fx/domain/fiat/entities/Symbol.java"
click node_rate "https://github.com/lue93/api-fx/blob/main/src/main/java/br/com/lue93/fx/domain/rate/entities/Rate.java"
click node_rateinput "https://github.com/lue93/api-fx/blob/main/src/main/java/br/com/lue93/fx/domain/rate/vo/RateInput.java"
click node_rateoutput "https://github.com/lue93/api-fx/blob/main/src/main/java/br/com/lue93/fx/domain/rate/vo/RateOutPut.java"
click node_ratecontract "https://github.com/lue93/api-fx/blob/main/src/main/java/br/com/lue93/fx/domain/rate/services/RateService.java"
click node_proxy "https://github.com/lue93/api-fx/blob/main/src/main/java/br/com/lue93/fx/application/services/rate/ProxyRateService.java"
click node_cache "https://github.com/lue93/api-fx/blob/main/src/main/java/br/com/lue93/fx/domain/rate/entities/RateCache.java"
click node_wise "https://github.com/lue93/api-fx/blob/main/src/main/java/br/com/lue93/fx/application/services/rate/WiseRateService.java"
click node_feign "https://github.com/lue93/api-fx/blob/main/src/main/java/br/com/lue93/fx/domain/rate/services/FeignWiseClient.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_controller,node_errors,node_openapi toneBlue
class node_usecase,node_fiatservice toneAmber
class node_fiatcontract,node_fiatdata,node_fiatresult,node_symbols,node_rate,node_rateinput,node_rateoutput,node_ratecontract,node_client toneMint
class node_proxy,node_cache,node_wise,node_feign toneRose
class node_wiseapi toneIndigo
```

## Components

### API boundary

- [Exchange endpoint](https://github.com/lue93/api-fx/blob/main/src/main/java/br/com/lue93/fx/adapters/controllers/FiatExchangeController.java): `src/main/java/br/com/lue93/fx/adapters/controllers/FiatExchangeController.java`
- [REST error mapping](https://github.com/lue93/api-fx/blob/main/src/main/java/br/com/lue93/fx/infra/spring/exception/RestControllerExceptionHandler.java): `src/main/java/br/com/lue93/fx/infra/spring/exception/RestControllerExceptionHandler.java`
- [API documentation](https://github.com/lue93/api-fx/blob/main/src/main/java/br/com/lue93/fx/infra/spring/doc/SpringDocConfig.java): `src/main/java/br/com/lue93/fx/infra/spring/doc/SpringDocConfig.java`

### Application flow

- [Exchange use case](https://github.com/lue93/api-fx/blob/main/src/main/java/br/com/lue93/fx/application/usecase/fiat/exchange/FiatExcxhangeUseCase.java): `src/main/java/br/com/lue93/fx/application/usecase/fiat/exchange/FiatExcxhangeUseCase.java`
- [Amount conversion](https://github.com/lue93/api-fx/blob/main/src/main/java/br/com/lue93/fx/application/services/fiat/FiatExchangeServiceWiseRates.java): `src/main/java/br/com/lue93/fx/application/services/fiat/FiatExchangeServiceWiseRates.java`

### Currency domain

- [Exchange contract](https://github.com/lue93/api-fx/blob/main/src/main/java/br/com/lue93/fx/domain/fiat/services/FiatExchangeService.java): `src/main/java/br/com/lue93/fx/domain/fiat/services/FiatExchangeService.java`
- [Exchange data](https://github.com/lue93/api-fx/blob/main/src/main/java/br/com/lue93/fx/domain/fiat/vo/FiatInputData.java): `src/main/java/br/com/lue93/fx/domain/fiat/vo/FiatInputData.java`
- [Converted amount](https://github.com/lue93/api-fx/blob/main/src/main/java/br/com/lue93/fx/domain/fiat/vo/FiatOutputData.java): `src/main/java/br/com/lue93/fx/domain/fiat/vo/FiatOutputData.java`
- [Currency symbols](https://github.com/lue93/api-fx/blob/main/src/main/java/br/com/lue93/fx/domain/fiat/entities/Symbol.java): `src/main/java/br/com/lue93/fx/domain/fiat/entities/Symbol.java`
- [Rate model](https://github.com/lue93/api-fx/blob/main/src/main/java/br/com/lue93/fx/domain/rate/entities/Rate.java): `src/main/java/br/com/lue93/fx/domain/rate/entities/Rate.java`
- [Rate request](https://github.com/lue93/api-fx/blob/main/src/main/java/br/com/lue93/fx/domain/rate/vo/RateInput.java): `src/main/java/br/com/lue93/fx/domain/rate/vo/RateInput.java`
- [Rate result](https://github.com/lue93/api-fx/blob/main/src/main/java/br/com/lue93/fx/domain/rate/vo/RateOutPut.java): `src/main/java/br/com/lue93/fx/domain/rate/vo/RateOutPut.java`
- [Rate contract](https://github.com/lue93/api-fx/blob/main/src/main/java/br/com/lue93/fx/domain/rate/services/RateService.java): `src/main/java/br/com/lue93/fx/domain/rate/services/RateService.java`

### Rate integration

- [Cached rate lookup](https://github.com/lue93/api-fx/blob/main/src/main/java/br/com/lue93/fx/application/services/rate/ProxyRateService.java): `src/main/java/br/com/lue93/fx/application/services/rate/ProxyRateService.java`
- [In-memory rate cache](https://github.com/lue93/api-fx/blob/main/src/main/java/br/com/lue93/fx/domain/rate/entities/RateCache.java): `src/main/java/br/com/lue93/fx/domain/rate/entities/RateCache.java`
- [Wise rate service](https://github.com/lue93/api-fx/blob/main/src/main/java/br/com/lue93/fx/application/services/rate/WiseRateService.java): `src/main/java/br/com/lue93/fx/application/services/rate/WiseRateService.java`
- [Wise HTTP client](https://github.com/lue93/api-fx/blob/main/src/main/java/br/com/lue93/fx/domain/rate/services/FeignWiseClient.java): `src/main/java/br/com/lue93/fx/domain/rate/services/FeignWiseClient.java`

### Other components

- **API caller**
- **Wise service**

## Connections

- API caller → Exchange endpoint: submits exchange
- Exchange endpoint → Exchange use case: invokes
- Exchange use case → Amount conversion: calculates amount
- Exchange use case → Cached rate lookup: requests rate
- Amount conversion → Converted amount: returns result
- Cached rate lookup → In-memory rate cache: checks and updates
- Cached rate lookup → Wise rate service: fetches on miss or expiry
- Wise rate service → Wise HTTP client: requests rates
- Wise HTTP client → Wise service: fetches rate
- Wise rate service → Rate result: builds result
- Wise HTTP client → Rate model: receives rates
- Exchange endpoint → REST error mapping: errors handled by