# Com / Github / Blaxk3

## Overview

`com.github.blaxk3` is the application area for a Swing-based currency converter. This module set appears to cover the full path from application startup to user interaction to remote exchange-rate lookup. In practice, it is split into three layers:

- `converter` bootstraps the desktop app,
- `ui` presents the window and handles user actions, and
- `api` talks to the external exchange-rate service.

Taken together, these sub-modules form a small but complete desktop workflow: launch the app, select currencies, enter an amount, fetch rates, and show the converted result.

## Sub-module Guide

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

The converter package is the entry point. It contains the `main` method that starts the UI on the Swing Event Dispatch Thread. This package does not perform conversion itself; instead, it acts as the handoff point into the presentation layer.

Its role in the system is to keep startup logic minimal and thread-safe. By using `SwingUtilities.invokeLater`, it ensures the UI is constructed in the correct Swing context.

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

The UI package owns the visible application window and most of the user-facing behavior. It builds the frame, input field, labels, buttons, and currency selectors. It also validates numeric input and loads currency codes in the background so the window remains responsive.

This module depends on the API package for two things:

- discovering valid currency codes,
- converting one currency amount into another.

In other words, `ui` is the orchestration layer that translates user gestures into service calls and then turns the results back into display text.

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

The api package wraps the external ExchangeRate-API service. It loads an API key from local configuration, builds request URLs, performs HTTP GET requests, parses JSON, and returns either the available currency codes or a conversion result.

This package is the system's integration boundary. The UI depends on it, but the package itself appears independent of the rest of the application. Its job is to hide transport details from the presentation layer.

### How they relate

The relationship is essentially one-directional:

1. `converter` starts the app.
2. `ui` creates the window and reacts to user input.
3. `api` performs remote lookups needed by the UI.

That structure keeps startup, presentation, and network access separated, even though the implementation is still compact.

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

## Key Patterns and Architecture

### Thin bootstrap, heavier UI

`converter` is intentionally small. The application starts in one place, but almost all behavior quickly moves into the UI package. This suggests the codebase is organized around a desktop presentation-first design rather than a layered backend architecture.

### Swing thread discipline

The startup flow uses `SwingUtilities.invokeLater`, which is the standard Swing pattern for safe UI initialization. The UI package also uses `SwingWorker` to load currency codes in the background. Together, these choices show a consistent concern for keeping work that might block off the Event Dispatch Thread.

### Direct service calls from the view layer

The UI calls `CurrencyRateAPI` directly instead of going through an intermediate service or controller layer. That keeps the code simple, but it also means the presentation layer is tightly coupled to the API contract and to the shape of the returned JSON data.

### Validation at the edge

Input is constrained in the UI before conversion is attempted. The numeric filter and button handler checks reduce the chance of bad requests being sent to the API, although the API class still needs defensive null handling because remote failures can occur independently of input validation.

### Implicit data flow

The application appears to flow through simple values rather than domain objects:

- currency codes as strings,
- amounts as `BigDecimal` into the API and `double` for display,
- results as strings returned from parsed JSON.

That keeps the system lightweight, but it also means the app relies heavily on consistent response shapes from the remote service.

## Dependencies and Integration

### External dependencies

This package group integrates with:

- **Swing/AWT** for the desktop UI,
- **`SwingUtilities` and `SwingWorker`** for thread-safe UI work,
- **Gson** for JSON parsing in the API layer,
- **SLF4J** for logging,
- the **ExchangeRate-API** remote service,
- a local **`config.properties`** resource for the API key.

### Internal integration

The only clear internal link in the child pages is from `ui` to `api`. `converter` links to `ui` by launching it. There are no other indexed package dependencies for this module, so the subpackages appear to be intentionally compact and loosely expanded from this root.

### Runtime coupling

The app depends on three runtime conditions:

- the Swing runtime must be available,
- `config.properties` must be packaged on the classpath,
- the external exchange-rate service must be reachable.

If any of these are missing, the UI may still open, but currency loading or conversion can fail.

## Notes for Developers

- This appears to be a small desktop application with a clear launch-to-UI-to-API flow, not a broader platform module.
- The UI is doing most of the coordination work, so changes to user interaction will likely be made there first.
- The API layer returns `null` on several failure paths, so callers should treat it as an unreliable network boundary rather than a guaranteed data source.
- Because the app uses live remote data, startup can succeed even if currency loading fails later in the background.
- The current design is simple and easy to follow, but it is also tightly coupled. If the project grows, a future refactor could introduce a service layer between the UI and the API to isolate request/response handling.
- The child pages indicate that the most important file for understanding behavior is `src/main/java/com/github/blaxk3/ui/UI.java`, since it holds the main window and the conversion workflow.