# Com / Github / Blaxk3

## Overview

The `com.github.blaxk3` area appears to be a small desktop currency-conversion application organized around three cooperating pieces: a launcher, a Swing UI, and an API client. Together they provide the full user journey from application startup to currency selection to remote exchange-rate lookup and result display.

At a high level, the package is structured as a thin startup layer (`converter`), an interactive presentation layer (`ui`), and an integration layer (`api`). The launcher boots the UI on the correct Swing thread, the UI gathers user input and presents results, and the API layer handles all communication with the external exchange-rate service.

## Sub-module Guide

### `converter`

The `com.github.blaxk3.converter` package is the application entry point. It contains the startup class that launches the Swing user interface and then steps out of the way.

This module does not implement business logic itself. Instead, it acts as the handoff point between the JVM and the UI layer. Its main responsibility is to make sure the UI is created on the Swing Event Dispatch Thread, which keeps the desktop application responsive and thread-safe.

### `ui`

The `com.github.blaxk3.ui` package is the interactive front end. It owns the main window, the amount field, the source and target currency selectors, and the buttons for converting, swapping, and clearing.

This module is where user intent enters the system. It also performs lightweight validation and formatting, but it delegates currency discovery and conversion to the API layer. It appears to be the orchestration center for the application: it coordinates background loading of currency codes, invokes conversion when the user clicks Convert, and updates the visible state.

### `api`

The `com.github.blaxk3.api` package is the service integration layer. It wraps the ExchangeRate-API HTTP calls and exposes convenience methods for retrieving supported currency codes and converting amounts between currency pairs.

This module hides the mechanics of configuration loading, URL construction, request execution, and JSON parsing. The rest of the application relies on it as a simple, purpose-built client rather than dealing with remote service details directly.

## How the pieces fit together

The three modules form a straightforward dependency chain:

1. `converter` starts the application.
2. `converter` creates the `ui`.
3. `ui` loads currency codes and requests conversions through `api`.
4. `api` calls the external ExchangeRate-API service and returns parsed results.

The relationship is intentionally one-way. The API layer does not know about the UI, and the converter layer does not participate in business logic. That keeps the system easy to follow, but it also means the UI is tightly coupled to the API contract.

## Key Patterns and Architecture

### Layered desktop application design

This area follows a simple layered design:

- **Startup layer** - `converter` launches the application safely.
- **Presentation layer** - `ui` manages widgets, events, validation, and display.
- **Integration layer** - `api` communicates with the external currency service.

That separation keeps the code compact while still giving each class a clear role.

### Event-driven UI orchestration

The UI is event driven. User actions such as clicking Convert, Swap, or Clear drive the next step in the workflow. The UI also uses background loading for currency-code population so the window can appear without waiting on network activity.

This appears to be the primary concurrency boundary in the system: startup and UI creation happen on the Swing thread, while code loading is offloaded to `SwingWorker` to avoid blocking the interface.

### Thin service wrapper around an external API

The API layer is intentionally narrow and direct. Rather than introducing a rich domain model, it works with the exchange-rate service response shape and returns only the specific values the UI needs.

That makes the current implementation simple, but it also means the UI and API are coupled to the external response structure. Any change in the remote payload is likely to affect the integration code and possibly the UI flow.

## Dependencies and Integration

### Internal dependencies

- [`com.github.blaxk3.converter`](converter.md) depends on the UI layer to create the desktop application.
- [`com.github.blaxk3.ui`](ui.md) depends on the API layer for currency code loading and conversion.
- [`com.github.blaxk3.api`](api.md) is the lowest-level module in this area and has no internal dependencies shown in the evidence.

### External integration

- **Swing / AWT** provides the desktop application framework.
- **SLF4J** is used for logging failures.
- **Gson** parses the remote JSON responses.
- **JDK networking APIs** provide HTTP request handling.
- **ExchangeRate-API** is the external service that supplies currency metadata and conversion values.

### Runtime data flow

A typical request moves through the system like this:

- The user enters an amount and selects two currencies in the UI.
- The UI validates the input and gathers the selected codes.
- The UI calls the API client with the amount and currency pair.
- The API client fetches and parses the remote response.
- The UI formats the returned value and displays it.

Currency-code loading follows a similar but simpler path, except it is done asynchronously and only populates the selectors.

## Mermaid Diagram

```mermaid
flowchart TD
Parent["com.github.blaxk3"] --> Converter["converter"]
Parent --> UI["ui"]
Parent --> API["api"]
Converter --> UI
UI --> API
API --> ExchangeRate["ExchangeRate-API"]
```

## Notes for Developers

- The application is small enough that responsibilities are still tightly coupled by design. That keeps the code easy to trace, but changes in the API contract will likely ripple into the UI.
- `converter` should remain focused on startup. Any non-trivial initialization logic should still respect Swing threading rules.
- `ui` is responsible for most of the user experience. If responsiveness becomes a problem, the conversion call is the first place to look for background execution.
- `api` currently behaves like a direct HTTP adapter rather than a domain service. If the application grows, this may be the place to introduce typed models or better error handling.
- Based on the available documentation, there are no additional child modules or deeper package hierarchies under `com.github.blaxk3`.