# Com / Github / Blaxk3

## Overview

The `com.github.blaxk3` area appears to be a small Swing-based currency converter application. At a system level, it is split into three responsibilities:

- **startup/bootstrapping** in `com.github.blaxk3.converter`
- **desktop presentation and interaction** in `com.github.blaxk3.ui`
- **external exchange-rate integration** in `com.github.blaxk3.api`

Taken together, these modules form a simple flow: the launcher starts the UI, the UI collects user input and displays results, and the API module talks to the remote exchange-rate service to fetch supported currencies or perform conversions.

## Sub-module Guide

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

This appears to be the application entry point. Its job is narrow but important: it starts the Swing UI on the Event Dispatch Thread by calling `SwingUtilities.invokeLater(UI::new)`.

In the larger system, this package is the handoff point between the JVM launch process and the actual user-facing application. It does not contain conversion logic itself; instead, it delegates immediately to the UI layer.

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

This package appears to implement the main desktop window for the converter. It builds the form, validates the amount field, loads currency codes in the background, and responds to button actions such as convert, swap, and clear.

Its role is both presentation and orchestration. The UI is where user interaction becomes application behavior: it gathers source and target currencies, reads the amount, calls the API layer, and displays the formatted result.

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

This package appears to be the integration layer for a third-party exchange-rate service. It centralizes API-key loading, URL construction, HTTP requests, and JSON parsing.

The UI depends on this module for two things:

- discovering supported currency codes
- requesting a conversion result for a currency pair and amount

So the API module is effectively the system's data provider, while the UI is the consumer of that data.

### How they relate

The relationship is intentionally layered:

- `converter` launches the app
- `ui` manages the screen and user actions
- `api` fetches remote currency data

That keeps startup concerns separate from presentation concerns, and presentation concerns separate from network and parsing logic. The result is a small but coherent pipeline from application launch to currency conversion display.

## Key Patterns and Architecture

### Thin bootstrapper, rich UI, focused integration

This codebase appears to follow a pragmatic, low-ceremony structure:

- the launcher is minimal
- the UI class does most of the coordination
- the API wrapper keeps third-party communication in one place

There is no separate controller, service, or repository layer visible in the documentation. Instead, the UI directly invokes `CurrencyRateAPI`, which suggests a compact desktop application rather than a heavily layered backend design.

### Event-driven Swing flow

The system is built around Swing's event-driven model:

- the application is created on the Event Dispatch Thread
- the UI installs button listeners for user actions
- currency code loading happens asynchronously with `SwingWorker`
- numeric input is constrained with a `DocumentFilter`

This appears to be designed to keep the interface responsive while remote currency data is loaded in the background.

### Data flow from remote service to screen

A typical conversion path looks like this:

1. the launcher creates the UI
2. the UI loads currency codes from the API layer
3. the user selects source and target currencies
4. the user enters an amount
5. the UI calls the API's conversion method
6. the formatted result is shown in the interface

That flow keeps the remote dependency hidden behind the UI, while still allowing the screen to reflect live exchange-rate data.

### Mermaid overview

```mermaid
flowchart LR
Converter["com.github.blaxk3.converter"] --> UI["com.github.blaxk3.ui"]
UI --> API["com.github.blaxk3.api"]
API --> ExchangeRate["ExchangeRate API v6"]
API --> Config["config.properties"]
UI --> Swing["Swing UI widgets"]
```

## Dependencies and Integration

### External dependencies

From the child module documentation, the main external pieces are:

- **Swing / AWT** for the desktop UI
- **SwingWorker** for background loading of currency codes
- **DocumentFilter** for input validation
- **Gson** for JSON parsing in the API layer
- **SLF4J** for logging
- **`java.net` / `java.io`** classes for HTTP access and resource loading
- **`BigDecimal`** and **`DecimalFormat`** for amount handling and display formatting

### Remote service integration

`com.github.blaxk3.api` integrates with the ExchangeRate API v6. The documented usage patterns are:

- `/latest/USD` to discover currency codes
- `/pair/{from}/{to}/{amount}` to request a conversion result

This module also depends on a classpath `config.properties` file containing `API_KEY`, so deployment and local development both need to provide that resource.

### Internal integration points

The key internal connection is from UI to API:

- the UI creates `CurrencyRateAPI` instances when populating combo boxes and handling conversion requests
- the converter package invokes the UI constructor as the startup path

No deeper cross-module graph was captured in the index, so this appears to be a small application with a direct dependency chain rather than a broad package network.

## Notes for Developers

- **Keep the startup path thread-safe.** `com.github.blaxk3.converter` already uses `SwingUtilities.invokeLater`, so additional UI startup work should stay on the Swing thread.
- **Expect asynchronous UI initialization.** The combo boxes are populated in the background, so callers should not assume they are immediately filled when the frame opens.
- **Handle API failure paths carefully.** The API layer returns `null` in some error cases and does not fully guard against malformed payloads, so the UI should remain defensive.
- **Configuration is required.** The exchange-rate client depends on a classpath `config.properties` file with `API_KEY`.
- **The UI currently owns coordination logic.** If the application grows, this would be the most likely place to introduce a separate controller or service abstraction.
- **Amount input is intentionally constrained.** The numeric filter accepts digits and one decimal point, which may need revision if negative values, localization, or richer validation become requirements.
- **This appears to be a compact desktop application rather than a multi-tier platform.** Most behavior is concentrated in a few classes, so changes tend to have broad impact across startup, UI, and API calls.

## Summary

`com.github.blaxk3` is organized as a simple currency-converter system with a clear separation between launching, presenting, and fetching exchange-rate data. The launcher opens the Swing UI, the UI handles user interaction and delegates to the API, and the API encapsulates the remote exchange-rate integration needed to populate currency choices and calculate conversions.