# Com / Github / Blaxk3

## Overview

The `com.github.blaxk3` area appears to implement a small desktop currency converter application built on Swing and backed by a remote exchange-rate API. The package structure suggests a clean separation between three concerns: application startup, user interface, and remote currency-rate access.

At a system level, the flow is simple but cohesive:

1. The launcher starts the Swing UI on the event dispatch thread.
2. The UI builds the converter window and gathers user input.
3. The API layer fetches currency codes and performs conversions through ExchangeRate-API.

This makes the package tree look like a small vertical slice of an application: one entry point, one presentation layer, and one integration layer for external exchange-rate data.

## Sub-module Guide

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

This package appears to be the application entry point. Its job is not to implement business behavior, but to start the desktop application correctly. The `main` method uses `SwingUtilities.invokeLater(...)` so that `UI` is created on Swing's event dispatch thread, which is the standard threading model for Swing applications.

This module is the top of the execution chain. It owns startup orchestration and hands off control to the UI layer.

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

This package appears to hold the visible application and most of the user workflow. The `UI` class builds the frame, input field, combo boxes, result display, and action buttons. It also contains two helper pieces that support the experience:

- `NumericFilter`, which limits the amount field to numeric input
- `CurrencyCode`, which loads currency codes in the background so the combo boxes can populate without freezing the window

`UI` depends on the API layer for two different tasks:

- loading supported currency codes
- converting an entered amount from one currency to another

In other words, this package is the orchestrator of the user journey, while the API package supplies the data and calculations behind that journey.

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

This package appears to be a thin client around ExchangeRate-API. It centralizes configuration loading, HTTP access, JSON parsing, and response extraction in one class, `CurrencyRateAPI`.

The UI uses this class as its external-data gateway. The API package is therefore a dependency of the UI, but it is not responsible for presentation. It acts as the integration boundary between the desktop app and the remote service.

### Relationship summary

- `converter` starts the application
- `ui` owns the interactive Swing experience
- `api` supplies remote currency data and conversion results

The relationship is one-way and layered: startup -> presentation -> integration.

### Mermaid diagram

```mermaid
flowchart TD
Launcher["CurrencyConverter"] --> UIClass["UI"]
UIClass --> NumericFilter["NumericFilter"]
UIClass --> CurrencyCode["CurrencyCode"]
CurrencyCode --> CurrencyRateAPI["CurrencyRateAPI"]
UIClass --> UserActions["Convert, Swap, Clear"]
CurrencyRateAPI --> ExchangeRateAPI["ExchangeRate API service"]
```

## Key Patterns and Architecture

### Layered responsibility

The codebase appears to follow a lightweight layered architecture:

- **Startup layer** - `CurrencyConverter` only launches the app
- **Presentation layer** - `UI` manages controls, layout, and user actions
- **Integration layer** - `CurrencyRateAPI` talks to the remote service

This keeps each piece focused and makes it easier to reason about changes. For example, updating the API endpoint should stay in `api`, while changing layout or controls should stay in `ui`.

### Threading model for Swing

The launcher and UI work together to respect Swing threading rules:

- `CurrencyConverter` creates the UI via `invokeLater`
- `CurrencyCode` uses `SwingWorker` to fetch currency codes off the UI thread

This appears to be the main concurrency pattern in the module. It avoids blocking the interface during startup and while data is loading.

### Thin wrappers over external behavior

The API layer is intentionally minimal. It does not introduce its own domain model; it simply forwards requests to the exchange-rate service and extracts fields from JSON. Similarly, the UI does not contain a separate presentation model; it keeps state directly in Swing components.

That simplicity reduces ceremony, but it also means failure handling is mostly implicit. The UI and API rely on `null` checks, logs, and the assumptions of the remote service.

### Data flow

A typical conversion appears to move through the system like this:

1. `CurrencyCode` asks `CurrencyRateAPI` for available codes.
2. The UI populates the currency selectors.
3. The user enters an amount and clicks Convert.
4. `UI` reads the selected currencies and amount.
5. `CurrencyRateAPI.convert(...)` calls the remote service.
6. The returned value is formatted and shown in the result label.

That sequence shows the UI as the coordinator and the API as the source of truth for conversion data.

## Dependencies and Integration

### Internal dependencies

From the child pages, the main internal dependency chain is:

- `com.github.blaxk3.converter` depends on `com.github.blaxk3.ui.UI`
- `com.github.blaxk3.ui` depends on `com.github.blaxk3.api.CurrencyRateAPI`

The API package does not appear to depend on either of the others.

### External dependencies

Across the sub-modules, the code relies on a small set of platform and library features:

- **Swing/AWT** for the desktop application and threading model
- **SLF4J** for logging
- **Gson** for JSON parsing
- **Java networking classes** for HTTP requests
- **`config.properties`** for runtime API configuration
- **ExchangeRate-API** as the remote data provider

### Integration points

The package appears to connect to the broader system in two major places:

- **Application startup** through `CurrencyConverter.main(...)`
- **Remote data access** through `CurrencyRateAPI`

Everything else is internal wiring between UI components and the API client.

## Notes for Developers

- This area appears to be a self-contained feature slice for currency conversion. If you are changing behavior, first decide whether the change belongs in startup, UI, or API integration.
- `CurrencyConverter` is intentionally small, so it is the right place for startup-only concerns such as alternate entry behavior or CLI-based configuration.
- `UI` owns the user experience and most of the interaction logic. Changes to validation, button behavior, or layout likely belong there.
- `CurrencyRateAPI` is a thin wrapper over the remote service. If reliability becomes more important, this is the place to add retries, better error handling, or stronger validation.
- The current design depends on the remote API being available and on `config.properties` being packaged correctly. Missing configuration can break the full conversion flow.
- This appears to be a feature set where UI responsiveness matters. The use of `SwingWorker` suggests the design already tries to keep network calls off the event dispatch thread.
- Because the package does not define its own domain model, the boundaries between UI state and remote JSON fields are fairly direct. That makes the code easy to follow, but also tightly coupled to response shape and Swing components.

## Source References

- [`src/main/java/com/github/blaxk3/converter/CurrencyConverter.java`](src/main/java/com/github/blaxk3/converter/CurrencyConverter.java:7)
- [`src/main/java/com/github/blaxk3/ui/UI.java`](src/main/java/com/github/blaxk3/ui/UI.java:30)
- [`src/main/java/com/github/blaxk3/api/CurrencyRateAPI.java`](src/main/java/com/github/blaxk3/api/CurrencyRateAPI.java:19)