# wildclown/ebury-challenge architecture

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

- Interactive diagram: https://gitdiagram.com/wildclown/ebury-challenge
- Repository: https://github.com/wildclown/ebury-challenge

## Overview

##### Project type and purpose
- This is primarily a single‐service “Flight Management” application (written in Kotlin/Spring Boot) that offers two interfaces:
a) A command-line interface (CLI) to load a CSV of flight routes, accept “ORIGIN-DEST” queries, and print the cheapest path.
b) A REST API (two endpoints) to register new routes (persisting back to the CSV) and query the best route.
- In addition, there is a small standalone “csv-to-json-converter” front-end utility: a static HTML+JS page that fetches the OpenAPI spec (Ebury.openapi.json) and a CSV file, converts the CSV flight data into JSON, and displays it in the browser.

##### File structure
Top-level:
- ebury-challenge/ → the Kotlin/Spring Boot application
- src/main/kotlin/br/com/ebury/config → application configuration
- controller → REST controller class with two endpoints
- service → business logic interfaces and implementations
- repository → data access interfaces and custom impl that read/write the CSV file
- model/dto/exceptions/validations → domain models, API DTOs, validation & error handlers
- resources → application.yaml and dev-specific YAML (no external DB; uses CSV file)
- test → unit tests for controller, service, validation layers
- docker-compose.yml and Gradle wrapper → containerization and build scripts
- .env.example → environment placeholders for CSV path, etc.
- csv-to-json-converter/ → static front-end
- index.html, csvConverter.js, openApiGetter.js → loads OpenAPI, fetches CSV, converts and displays JSON
- Ebury.openapi.json → OpenAPI specification for the REST API
- input-example.csv → sample flight routes input

##### README
- Describes the problem: find cheapest route ignoring number of hops
- CLI invocation: mysolution input-routes.csv
- Two REST interfaces:
- POST /routes – register new route (append to CSV)
- GET /routes/{from}/{to} – return best route and cost
- Recommendations: containerize, write unit tests, document API & design decisions

##### What
- Client – two types of consumers:
· CLI Client (console)
· REST Client (e.g., Postman, Front-end)
- Flight Management Service (Spring Boot application) comprising:
· Controller layer (REST endpoints)
· CLI‐runner component (logic that boots on application start to read args)
· Service layer (FlightManagementService)
· Repository layer (CustomFlightRouteRepository / FlightRouteRepository)
- Persistence – CSV file (input-routes.csv) as primary datastore
- csv-to-json-converter app (static web page + JS)
- OpenAPI specification (Ebury.openapi.json) as contract
- CLI Client → Service start-up → Repository reads CSV → service computes queries → CLI prints output
- REST Client → Controller endpoints → Service layer → Repository reads/appends CSV → Controller returns JSON response
- Converter front-end → openApiGetter.js fetches Ebury.openapi.json → csvConverter.js fetches input-routes.csv (or via API) → displays JSON
c. Architectural patterns & principles:
- Layered architecture (Controller → Service → Repository)
- Single responsibility: each layer only handles its own concern
- CSV file as a simple persistence mechanism (no external DB)
- Exception handling centralized in GlobalExceptionHandler
- Validation logic separated into controller/service validation classes
- Containerized deployment with Docker Compose
d. Key technologies/frameworks:
- Kotlin + Spring Boot Web
- Gradle + Docker Compose
- Static HTML/JavaScript for converter
- OpenAPI (Swagger) specification

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    subgraph "Clients" 
        direction TB
        CLIClient["CLI Client"]:::client
        RESTClient["REST Client (e.g., Postman)"]:::client
        ConverterUI["Converter Front-end"]:::frontend
    end

    %% Docker Container for Spring Boot App
    subgraph "Docker Container" 
        direction TB
        subgraph "Flight Management Service" 
            direction TB
            CLIRunner["CLI Runner Component"]:::spring
            Controller["REST Controller"]:::spring
            ServiceI["Service Interface"]:::spring
            ServiceImpl["Service Implementation"]:::spring
            RepoI["Repository Interfaces"]:::spring
            RepoImpl["Repository Implementation"]:::spring
            Models["Domain Models & DTOs"]:::spring
            Config["Configuration"]:::spring
            ExceptionHandler["Global Exception Handler"]:::spring
            Validation["Validation Logic"]:::spring
        end
    end

    %% Persistence and Specs
    CSVFile["CSV File (input-example.csv)"]:::persistence
    OpenAPI["OpenAPI Spec (Ebury.openapi.json)"]:::spec

    %% Converter frontend assets
    IndexHTML["index.html"]:::frontend
    CSVConvJS["csvConverter.js"]:::frontend
    OpenAPIJS["openApiGetter.js"]:::frontend

    %% Data Flows
    CLIClient -->|"CLI args"| CLIRunner
    CLIRunner -->|"calls"| ServiceImpl
    ServiceImpl -->|"uses"| RepoI
    RepoI -->|"delegates to"| RepoImpl
    RepoImpl -->|"reads/writes CSV"| CSVFile
    ServiceImpl -->|"returns result"| CLIRunner

    RESTClient -->|"HTTP/JSON"| Controller
    Controller -->|"invokes"| ServiceImpl
    ServiceImpl -->|"uses"| RepoI
    RepoI -->|"delegates to"| RepoImpl
    RepoImpl -->|"reads/writes CSV"| CSVFile
    Controller -->|"HTTP/JSON"| RESTClient

    ConverterUI -->|"fetch Ebury.openapi.json"| OpenAPIJS
    ConverterUI -->|"fetch CSV file"| CSVConvJS
    OpenAPIJS -->|"requests"| OpenAPI
    CSVConvJS -->|"requests"| CSVFile

    %% Subgraph for Converter UI assets
    subgraph "Static Converter Front-end" 
        direction TB
        IndexHTML
        CSVConvJS
        OpenAPIJS
    end

    %% Click Events
    click CLIRunner "https://github.com/wildclown/ebury-challenge/blob/main/ebury-challenge/src/main/kotlin/br/com/ebury/FlightManagementApplication.kt"
    click Controller "https://github.com/wildclown/ebury-challenge/blob/main/ebury-challenge/src/main/kotlin/br/com/ebury/controller/FlightManagementController.kt"
    click ServiceI "https://github.com/wildclown/ebury-challenge/blob/main/ebury-challenge/src/main/kotlin/br/com/ebury/service/FlightManagementService.kt"
    click ServiceImpl "https://github.com/wildclown/ebury-challenge/blob/main/ebury-challenge/src/main/kotlin/br/com/ebury/service/impl/FlightManagementServiceImpl.kt"
    click RepoI "https://github.com/wildclown/ebury-challenge/blob/main/ebury-challenge/src/main/kotlin/br/com/ebury/repository/FlightRouteRepository.kt"
    click RepoI "https://github.com/wildclown/ebury-challenge/blob/main/ebury-challenge/src/main/kotlin/br/com/ebury/repository/CustomFlightRouteRepository.kt"
    click RepoImpl "https://github.com/wildclown/ebury-challenge/blob/main/ebury-challenge/src/main/kotlin/br/com/ebury/repository/impl/CustomFlightRouteRepositoryImpl.kt"
    click CSVFile "https://github.com/wildclown/ebury-challenge/blob/main/input-example.csv"
    click OpenAPI "https://github.com/wildclown/ebury-challenge/blob/main/Ebury.openapi.json"
    click IndexHTML "https://github.com/wildclown/ebury-challenge/blob/main/csv-to-json-converter/index.html"
    click CSVConvJS "https://github.com/wildclown/ebury-challenge/blob/main/csv-to-json-converter/csvConverter.js"
    click OpenAPIJS "https://github.com/wildclown/ebury-challenge/blob/main/csv-to-json-converter/openApiGetter.js"

    %% Styles
    classDef client fill:#ffa500,stroke:#333,stroke-width:1px
    classDef frontend fill:#f4d03f,stroke:#333,stroke-width:1px
    classDef spring fill:#85c1e9,stroke:#333,stroke-width:1px
    classDef persistence fill:#82e0aa,stroke:#333,stroke-width:1px
    classDef spec fill:#d7bde2,stroke:#333,stroke-width:1px
```
