# Getting Started

## What This Project Does
This is a Java Swing desktop app for currency conversion. It loads live exchange rates from the ExchangeRate-API service, lets you pick a source and target currency, and shows the converted result in the UI.

The codebase is small and centered around three main areas: app startup, API access, and the Swing user interface.

## Recommended Reading Order
1. Start with the app entry point: [`src/main/java/com/github/blaxk3/converter/CurrencyConverter.java`](../../src/main/java/com/github/blaxk3/converter/CurrencyConverter.java)
2. Then read the API client: [`src/main/java/com/github/blaxk3/api/CurrencyRateAPI.java`](../../src/main/java/com/github/blaxk3/api/CurrencyRateAPI.java)
3. Finish with the UI: [`src/main/java/com/github/blaxk3/ui/UI.java`](../../src/main/java/com/github/blaxk3/ui/UI.java)
4. Check runtime configuration in [`src/main/resources/config.properties`](../../src/main/resources/config.properties)
5. Review build and dependency setup in [`pom.xml`](../../pom.xml)

## Key Entry Points
There are no highly connected classes in this repository, so the main entry points are the top-level application classes:

- [`CurrencyConverter`](../../src/main/java/com/github/blaxk3/converter/CurrencyConverter.java) — starts the Swing UI on the event dispatch thread.
- [`CurrencyRateAPI`](../../src/main/java/com/github/blaxk3/api/CurrencyRateAPI.java) — loads the API key, builds request URLs, and fetches exchange-rate data.
- [`UI`](../../src/main/java/com/github/blaxk3/ui/UI.java) — builds the window, wires the buttons, and handles input validation.

## Project Structure
The source code is organized by responsibility:

- `src/main/java/com/github/blaxk3/converter/` — application bootstrap and entry point
- `src/main/java/com/github/blaxk3/api/` — HTTP and JSON integration with the exchange-rate service
- `src/main/java/com/github/blaxk3/ui/` — Swing frame, controls, and UI behavior
- `src/main/resources/` — runtime resources such as `config.properties` and the app icon

At a high level, the flow is:

```mermaid
flowchart TD
    AppStart["CurrencyConverter"] --> UIFrame["UI"]
    UIFrame --> ApiClient["CurrencyRateAPI"]
    ApiClient --> ExchangeService["ExchangeRate API"]
```

## Configuration
The most important configuration files are:

- [`src/main/resources/config.properties`](../../src/main/resources/config.properties) — stores `API_KEY`, which is required to call ExchangeRate-API.
- [`pom.xml`](../../pom.xml) — defines the Maven project, Java 23 compiler target, and dependencies.

A few practical notes:

- `API_KEY` must be replaced with a valid ExchangeRate-API key before the app can fetch rates.
- The app currently reads config from the classpath, so keep `config.properties` in `src/main/resources`.
- Dependencies include Gson for JSON parsing and SLF4J for logging.

## Common Patterns
You will see these patterns repeatedly in the codebase:

- **Small, direct classes** — most classes do one thing and keep the control flow simple.
- **Swing event dispatch thread startup** — the app creates the UI with `SwingUtilities.invokeLater(...)`.
- **Background UI loading** — currency codes are fetched with `SwingWorker` so the window stays responsive.
- **Document filtering for input** — the amount field uses a `DocumentFilter` to accept only numeric input.
- **Defensive null checks** — `Objects.requireNonNull(...)` is used around selected combo-box values and resources.
- **Basic SLF4J logging** — errors are logged rather than silently ignored.

## Where to Go Next
If you are new to this codebase, read the entry point first, then trace one user action end-to-end:

1. Start the app in [`CurrencyConverter`](../../src/main/java/com/github/blaxk3/converter/CurrencyConverter.java)
2. Follow how the UI builds its controls in [`UI`](../../src/main/java/com/github/blaxk3/ui/UI.java)
3. Trace a conversion request into [`CurrencyRateAPI`](../../src/main/java/com/github/blaxk3/api/CurrencyRateAPI.java)
4. Confirm the API key and dependency setup in [`config.properties`](../../src/main/resources/config.properties) and [`pom.xml`](../../pom.xml)

That path gives you the fastest mental model for how the app boots, loads currencies, and performs conversions.