# Com / Github / Blaxk3

## Overview

`com.github.blaxk3` appears to be a small currency-conversion application organized into three cooperating layers:

- a bootstrap layer that starts the program,
- a Swing UI layer that collects user input and displays results, and
- an API client layer that talks to ExchangeRate API v6.

Taken together, these modules form a thin desktop application for looking up available currency codes and converting amounts between currencies. The structure suggests a deliberately simple flow: the launcher creates the UI, the UI calls the API client, and the API client performs configuration loading plus HTTP/JSON work against the external service.

## Sub-module Guide

### `com.github.blaxk3.converter`

The `converter` package is the application entry point. It does not contain conversion logic itself; instead, it starts the Swing UI on the Event Dispatch Thread through `SwingUtilities.invokeLater(UI::new)`.

This package acts as the handoff point between the JVM startup lifecycle and the rest of the application. In other words, it is responsible for bootstrapping, not behavior.

### `com.github.blaxk3.ui`

The `ui` package appears to contain the user-facing desktop experience. It builds the main window, collects the source currency, target currency, and amount, and then triggers conversion requests when the user clicks Convert.

This package depends on the API layer for two distinct jobs:

- loading currency codes to populate the combo boxes, and
- sending conversion requests when the user wants a result.

It also contains local UI support pieces that keep the experience usable:

- `NumericFilter` constrains the amount field to numeric input,
- `CurrencyCode` loads codes asynchronously so the UI stays responsive, and
- the main `UI` frame manages swap, clear, and display behavior.

### `com.github.blaxk3.api`

The `api` package is the data-access layer for ExchangeRate API v6. It loads the API key from `config.properties`, builds endpoint URLs, executes HTTP requests, parses JSON, and exposes convenience methods for listing supported currency codes and converting one amount to another.

This layer is the lowest-level part of the system in the available documentation. The UI layer delegates to it rather than constructing HTTP requests itself, which keeps network and parsing concerns centralized in one place.

## How the Sub-modules Relate

The relationship between the packages is mostly one-directional:

1. `converter` starts the application.
2. `ui` presents the desktop interface.
3. `ui` calls into `api` for external data and conversion results.
4. `api` talks to the remote ExchangeRate service and reads local configuration.

That separation keeps the startup code thin, the interface code focused on interaction, and the API code focused on integration with the remote service.

```mermaid
flowchart TD
    Converter["CurrencyConverter"] --> UI["UI"]
    UI --> Api["CurrencyRateAPI"]
    UI --> NumericFilter["UI.NumericFilter"]
    UI --> CurrencyCode["UI.CurrencyCode"]
    CurrencyCode --> Api
    Api --> ExchangeRate["ExchangeRate API v6"]
    Api --> Config["config.properties"]
```

## Key Patterns and Architecture

### Layered responsibility split

This area appears to follow a very small layered architecture:

- **Bootstrap layer** — starts the app and keeps startup code out of the UI implementation.
- **Presentation layer** — owns window layout, user input, display formatting, and local validation.
- **Integration layer** — owns endpoint construction, HTTP execution, and JSON extraction.

That split reduces coupling between UI behavior and remote-service concerns. The UI does not appear to know about HTTP details, and the API layer does not appear to know about Swing widgets.

### Asynchronous UI loading

The UI package uses `SwingWorker` to load currency codes in the background. This appears to be a deliberate responsiveness pattern: the interface can open immediately while the code list is fetched from the API, rather than freezing the EDT during network I/O.

### Minimal, direct error handling

The overall code style in the documented modules appears to favor direct calls with lightweight error handling:

- the API layer logs failures and may return `null`,
- the UI layer validates some inputs locally, but may throw runtime exceptions if URL construction or API access fails,
- the converter package does not add any error logic of its own.

This keeps the code compact, but it means callers need to be defensive around nulls and malformed responses.

### Simple data flow

The main data flow is straightforward:

- the API layer returns currency codes as `String[]`,
- the UI layer sorts and inserts those codes into combo boxes,
- user input is parsed into numeric form before conversion,
- the returned conversion result is formatted back into a display string.

That indicates the system is designed around a simple request/response cycle rather than a richer domain model.

## Dependencies and Integration

### External dependencies

Across the documented sub-modules, the main external dependencies are:

- **Swing / AWT** for the desktop UI and event dispatching,
- **SwingWorker** for background loading,
- **Gson** for JSON parsing,
- **SLF4J** for logging,
- **JDK networking APIs** for HTTP calls, and
- **`config.properties`** for API key configuration.

### Service integration

The only named remote integration is ExchangeRate API v6 at `https://v6.exchangerate-api.com/v6/`. The API client builds requests against that service and expects the response shape to include fields such as `conversion_rates` and `conversion_result`.

### Internal integration

The packages connect cleanly through direct class references:

- `CurrencyConverter` references `UI` as the startup target.
- `UI` references `CurrencyRateAPI` for both code lookup and conversion.
- `CurrencyCode` inside `UI` uses `CurrencyRateAPI` asynchronously.

The result is a narrow integration surface: a single launcher, a single frame class, and a single API client class are carrying the system.

## Notes for Developers

- `CurrencyConverter` should stay thin. If startup needs to grow, consider keeping parsing or initialization steps separate from UI creation so the entry point remains easy to reason about.
- `UI` is doing a lot of orchestration: layout, validation, formatting, async loading, and API calls. If that class becomes harder to maintain, it may be worth extracting more behavior into helpers or services.
- `CurrencyRateAPI` depends on `config.properties` being available on the classpath. Missing configuration will affect both currency discovery and conversion.
- The API layer appears to return `null` on several failure paths, while the UI layer sometimes assumes successful responses. Any changes in this area should be careful about null handling and user-facing error messages.
- The currency-code loading path is asynchronous, which is good for responsiveness, but it also means UI state is partially populated after startup. Code that assumes the combo boxes are immediately filled may fail.
- `NumericFilter` only validates characters, not full numeric semantics. If the application needs stricter money input rules, that validation likely needs to be expanded.
- The documented modules do not show shared domain models or service abstractions. This appears to be an intentionally small codebase with direct coupling between layers rather than a heavily abstracted architecture.