# seadmustafa/fxapi architecture

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

- Interactive diagram: https://gitdiagram.com/seadmustafa/fxapi
- Repository: https://github.com/seadmustafa/fxapi

## Overview

##### Project type and purpose
- This is a backend microservice: a Spring Boot–based REST API for currency conversion.
- It exposes endpoints for single conversions, bulk CSV conversions, exchange‐rate lookups, and conversion history.
- It fetches live rates from Fixer.io, caches them, and persists transaction history in an embedded H2 database.

##### File structure
- Top‐level artifacts:
- Dockerfile & docker-compose.yml (containerization, multi-container orchestration)
- pom.xml & Maven wrapper (build & dependency management)
- .env.local (external configuration for API keys)
- currencydata.csv (sample data for bulk processing)
- src/main/java/com/forex/api/:
- config (CacheConfig, ExternalApiConfig, OpenApiConfig)
- controller (three REST controllers)
- service & service/impl (business logic + caching layer)
- repository (Spring Data JPA for ConversionHistory)
- entity (ConversionHistory JPA entity)
- dto (request/response models)
- utils (FixerApiClient with @Retryable, UUIDGenerator)
- exception (global exception handling)
- src/main/resources: Spring profiles, OpenAPI banner, H2 console settings, sample images.
- Tests mirror controllers, services, and the Fixer client.

##### README for additional insights
- Clean layered architecture: external communication, caching, business logic, persistence, DTOs
- Uses Spring Retry for resilient external calls
- Swagger/OpenAPI docs for API exploration
- H2 console for runtime DB inspection

##### Elements
- Controllers (blue)
- Business services (green)
- External systems (orange)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Clients and UIs
    Client["HTTP Client\n(curl, Postman, Browser)"]:::external
    SwaggerUI["Swagger UI"]:::external
    H2Console["H2 Console"]:::external
    FixerIO["Fixer.io REST API"]:::external

    %% Docker and Compose
    Docker["Docker Container"]:::infra
    Compose["Docker Compose"]:::infra

    %% Main Application Container
    subgraph "FX API Application" 
        direction TB

        %% Configuration
        subgraph "Configuration" 
            direction TB
            OpenApiConfig["OpenApiConfig"]:::config
            CacheConfig["CacheConfig"]:::config
            ExternalApiConfig["ExternalApiConfig"]:::config
        end

        FxApiApp["FxApiApplication"]:::infra

        %% Controllers
        subgraph "Controllers" 
            direction TB
            CCCtrl["CurrencyConversionController"]:::controllers
            BFPCtrl["BulkFileProcessingController"]:::controllers
            ERCtrl["ExchangeRateController"]:::controllers
        end

        %% Services
        subgraph "Service Layer" 
            direction TB
            ERServiceIntf["ExchangeRateService"]:::services
            ERServiceImpl["ExchangeRateServiceImpl"]:::services
            ERCacheService["ExchangeRateCacheService"]:::services
            CCServiceIntf["CurrencyConversionService"]:::services
            CCServiceImpl["CurrencyConversionServiceImpl"]:::services
            BFPServiceIntf["BulkFileProcessingService"]:::services
            BFPServiceImpl["BulkFileProcessingServiceImpl"]:::services
        end

        %% Utilities
        subgraph "Utilities" 
            direction TB
            FixerClient["FixerApiClient"]:::utils
            UUIDGen["UUIDGenerator"]:::utils
        end

        %% Persistence
        subgraph "Persistence" 
            direction TB
            ConvEntity["ConversionHistory Entity"]:::database
            ConvRepo["ConversionHistoryRepository"]:::database
            H2DB["H2 In-memory Database"]:::database
        end

        %% DTOs and Exceptions
        subgraph "Models & Exceptions"
            direction TB
            DTOs["DTOs\n(request/response)"]:::infra
            GlobalEx["GlobalExceptionHandler"]:::infra
            AppEx["ForexAppException"]:::infra
        end
    end

    %% Relationships
    Client -->|HTTP Request| CCCtrl
    Client -->|HTTP Request| BFPCtrl
    Client -->|HTTP Request| ERCtrl
    SwaggerUI -->|OpenAPI Endpoint| FxApiApp
    H2Console -->|DB Console| H2DB
    FixerIO <-->|REST Calls with Retry| FixerClient

    %% Config to App
    OpenApiConfig --> FxApiApp
    CacheConfig --> FxApiApp
    ExternalApiConfig --> FxApiApp

    %% App to Controllers
    FxApiApp --> CCCtrl
    FxApiApp --> BFPCtrl
    FxApiApp --> ERCtrl

    %% Controllers to Services
    CCCtrl -->|calls| CCServiceImpl
    BFPCtrl -->|calls| BFPServiceImpl
    ERCtrl -->|calls| ERServiceImpl

    %% Service to Cache & External
    ERServiceImpl --> ERCacheService
    ERCacheService -->|cache miss| FixerClient
    ERServiceImpl --> ConvRepo
    CCServiceImpl --> ERServiceImpl
    CCServiceImpl --> ConvRepo
    BFPServiceImpl --> CCServiceImpl

    %% Utilities
    FixerClient --> UUIDGen

    %% Repository to Entity and Database
    ConvRepo --> ConvEntity
    ConvRepo --> H2DB

    %% DTOs and Exception Handling
    CCCtrl --> DTOs
    BFPCtrl --> DTOs
    ERCtrl --> DTOs
    GlobalEx --> CCCtrl
    GlobalEx --> BFPCtrl
    GlobalEx --> ERCtrl
    GlobalEx --> FxApiApp

    %% Docker orchestration
    Docker --> FxApiApp
    Compose --> Docker

    %% Click Events
    click FxApiApp "https://github.com/seadmustafa/fxapi/blob/main/src/main/java/com/forex/api/FxApiApplication.java"
    click OpenApiConfig "https://github.com/seadmustafa/fxapi/blob/main/src/main/java/com/forex/api/config/OpenApiConfig.java"
    click CacheConfig "https://github.com/seadmustafa/fxapi/blob/main/src/main/java/com/forex/api/config/CacheConfig.java"
    click ExternalApiConfig "https://github.com/seadmustafa/fxapi/blob/main/src/main/java/com/forex/api/config/ExternalApiConfig.java"
    click CCCtrl "https://github.com/seadmustafa/fxapi/blob/main/src/main/java/com/forex/api/controller/CurrencyConversionController.java"
    click BFPCtrl "https://github.com/seadmustafa/fxapi/blob/main/src/main/java/com/forex/api/controller/BulkFileProcessingController.java"
    click ERCtrl "https://github.com/seadmustafa/fxapi/blob/main/src/main/java/com/forex/api/controller/ExchangeRateController.java"
    click ERServiceIntf "https://github.com/seadmustafa/fxapi/blob/main/src/main/java/com/forex/api/service/ExchangeRateService.java"
    click ERServiceImpl "https://github.com/seadmustafa/fxapi/blob/main/src/main/java/com/forex/api/service/impl/ExchangeRateServiceImpl.java"
    click ERCacheService "https://github.com/seadmustafa/fxapi/blob/main/src/main/java/com/forex/api/service/ExchangeRateCacheService.java"
    click CCServiceIntf "https://github.com/seadmustafa/fxapi/blob/main/src/main/java/com/forex/api/service/CurrencyConversionService.java"
    click CCServiceImpl "https://github.com/seadmustafa/fxapi/blob/main/src/main/java/com/forex/api/service/impl/CurrencyConversionServiceImpl.java"
    click BFPServiceIntf "https://github.com/seadmustafa/fxapi/blob/main/src/main/java/com/forex/api/service/BulkFileProcessingService.java"
    click BFPServiceImpl "https://github.com/seadmustafa/fxapi/blob/main/src/main/java/com/forex/api/service/impl/BulkFileProcessingServiceImpl.java"
    click FixerClient "https://github.com/seadmustafa/fxapi/blob/main/src/main/java/com/forex/api/utils/FixerApiClient.java"
    click UUIDGen "https://github.com/seadmustafa/fxapi/blob/main/src/main/java/com/forex/api/utils/UUIDGenerator.java"
    click ConvEntity "https://github.com/seadmustafa/fxapi/blob/main/src/main/java/com/forex/api/entity/ConversionHistory.java"
    click ConvRepo "https://github.com/seadmustafa/fxapi/blob/main/src/main/java/com/forex/api/repository/ConversionHistoryRepository.java"
    click DTOs "https://github.com/seadmustafa/fxapi/tree/main/src/main/java/com/forex/api/dto/"
    click GlobalEx "https://github.com/seadmustafa/fxapi/blob/main/src/main/java/com/forex/api/exception/GlobalExceptionHandler.java"
    click AppEx "https://github.com/seadmustafa/fxapi/blob/main/src/main/java/com/forex/api/exception/ForexAppException.java"

    %% Styles
    classDef controllers fill:#D0E6FF,stroke:#0366d6;
    classDef services fill:#DFF5D8,stroke:#28a745;
    classDef external fill:#FFE3B3,stroke:#d98310;
    classDef database fill:#F0D6FF,stroke:#7A3E9D,stroke-width:2px;
    classDef utils fill:#E2E2E2,stroke:#666666;
    classDef config fill:#F5F5F5,stroke:#AAAAAA;
    classDef infra fill:#F0F0F0,stroke:#555555;
```
