# Com / Github / Blaxk3

## Overview

`com.github.blaxk3` is a small Swing-based currency converter application. This area of the codebase appears to be organized around a simple user flow: start the desktop app, load supported currency codes, let the user enter an amount, and call a remote exchange-rate service to compute the converted value.

The package is split into three cooperating layers:

- **`com.github.blaxk3.converter`** provides the application entry point and starts Swing correctly on the Event Dispatch Thread.
- **`com.github.blaxk3.ui`** owns the visible desktop experience, user input, and event handling.
- **`com.github.blaxk3.api`** isolates HTTP access to the ExchangeRate API and hides the details of request construction and JSON parsing.

Together, these modules form a thin desktop client: the converter package launches the app, the UI package orchestrates interactions, and the API package performs the remote data lookup and conversion work.

## Sub-module Guide

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

This module is the bootstrap boundary. Its `main` method does not implement conversion behavior itself; instead, it schedules UI creation with `SwingUtilities.invokeLater` so the application starts in Swing's expected threading model.

In system terms, this package is the first handoff point. It starts the app and transfers control to the UI layer.

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

This module is the presentation and interaction layer. It builds the main window, wires the amount field, currency selectors, and action buttons, and coordinates the conversion flow.

It also contains two supporting inner classes:

- `NumericFilter`, which constrains amount input to numeric values with a single decimal point.
- `CurrencyCode`, which fetches supported currency codes in the background so the window can render without waiting on network requests.

This package sits between the user and the API. It is responsible for validating input, loading reference data, formatting results, and updating the visible form state.

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

This module is the service integration layer. It wraps the ExchangeRate API, loads configuration from `config.properties`, builds endpoint URLs, executes HTTP requests, and parses JSON responses.

From the UI's perspective, this package is the source of truth for currency metadata and conversion results. From the application's perspective, it is the only part that knows how to talk to the remote service.

### How the sub-modules relate

The relationship is intentionally layered:

1. `CurrencyConverter` starts the UI on the Swing event thread.
2. `UI` creates the window and kicks off asynchronous currency-code loading.
3. `CurrencyCode` calls `CurrencyRateAPI.getCurrencyCode()` to populate both combo boxes.
4. When the user clicks Convert, `UI` calls `CurrencyRateAPI.convert(...)` with the selected currencies and entered amount.

This appears to be a simple request/response UI built on top of a small API client, with the UI doing orchestration and the API module doing network work.

## Key Patterns and Architecture

### Layered responsibility

The codebase is organized by responsibility rather than by feature size:

- **Launcher layer**: starts the JVM application safely.
- **Presentation layer**: renders the form and manages interaction state.
- **Integration layer**: handles remote HTTP calls and response parsing.

That separation keeps Swing concerns, input validation, and network access from being mixed together in one class.

### Event-driven UI flow

The application is built around user actions and Swing callbacks. The UI responds to button presses, combo-box population callbacks, and background worker completion events. The converter package only starts the process; the UI owns the runtime behavior after launch.

### Asynchronous loading for responsiveness

Currency code loading is intentionally backgrounded through `SwingWorker`. That means the window can appear before the network request finishes, which avoids blocking the Event Dispatch Thread.

The same pattern is important for overall UX: the UI stays responsive while reference data is fetched.

### Input guarding before conversion

`NumericFilter` prevents most invalid amount values from ever reaching the conversion handler. That design shifts validation earlier in the flow so the Convert action can assume a more constrained input shape.

### Direct service coupling with thin abstraction

`CurrencyRateAPI` is a thin wrapper around the ExchangeRate API rather than a broad domain service. It exposes only the operations the UI needs: supported currency codes and pair conversion.

This appears to favor simplicity over abstraction depth. There is no intermediary domain model; the UI works with strings, combo-box items, and formatted numeric results.

### Mermaid interaction diagram

```mermaid
flowchart LR
Converter["com.github.blaxk3.converter"] --> UI["com.github.blaxk3.ui"]
UI --> API["com.github.blaxk3.api"]
API --> ExchangeRateAPI["ExchangeRate API"]
UI --> SwingWorker["SwingWorker background loading"]
UI --> NumericFilter["NumericFilter input guard"]
```

## Dependencies and Integration

### External dependencies

The sub-modules rely on a small set of external libraries and JDK APIs:

- **Swing / AWT** for the desktop UI
- **`SwingUtilities`** for event-thread startup
- **`SwingWorker`** for asynchronous loading
- **`DocumentFilter`** for input restriction
- **Gson** for JSON parsing in the API layer
- **SLF4J** for logging
- **Java networking classes** such as `HttpURLConnection`, `URL`, and `URI`
- **`BigDecimal`** for passing amounts to the API conversion call

### Configuration and runtime inputs

The API layer expects a `config.properties` file on the classpath with an `API_KEY` entry. Without that configuration, request construction cannot succeed.

### External service integration

`com.github.blaxk3.api` integrates with the ExchangeRate API at `https://v6.exchangerate-api.com/v6/`. The UI depends on this service indirectly for both currency-code lists and conversion results.

### Internal integration path

The flow between modules is straightforward:

- `converter` depends on `ui`
- `ui` depends on `api`
- `api` depends on the remote ExchangeRate service and local configuration

This creates a one-way dependency chain that keeps startup, presentation, and network access separated.

## Notes for Developers

- The launcher is intentionally minimal. If you need new startup behavior, this is probably still the right entry point, but most product changes will live in `ui` or `api`.
- `UI` constructs the full window immediately, so any new initialization work may affect startup time or thread behavior.
- Currency loading is asynchronous, so code that assumes combo boxes are populated immediately after construction may be incorrect.
- `NumericFilter` is strict by design and does not allow signs or multiple decimal points. That means negative values are not currently part of the supported input model.
- The API layer is thin and nullable. Callers should expect missing configuration or network failures and handle those cases explicitly.
- The current design couples UI behavior to the specific ExchangeRate API response shape. If the remote API changes, `api` and any UI assumptions about its output will likely need to change together.

## Module Summary

This package acts as a small, layered desktop application: the converter package launches the app, the UI package manages the user experience, and the API package supplies currency data and conversion results from an external service. The architecture is simple, direct, and optimized for a single conversion workflow rather than a broad platform of reusable components.