# Getting Started

If you just joined this codebase, start with the app flow: the application launches the Swing UI, the UI calls the exchange-rate service, and the service reads the API key from resources before making live requests. The project is small, so the quickest way to understand it is to read the three Java classes in that order, then inspect the resource configuration.

## What This Project Does

This is a desktop **currency converter** built with Java Swing. Users choose two currencies, enter an amount, and the app fetches live exchange-rate data from ExchangeRate-API to calculate the conversion.

The codebase is intentionally compact: there is one main launcher, one UI class, and one API client. That makes it a good project to learn the end-to-end path from UI event handling to network request to formatted result.

## Recommended Reading Order

1. **Project overview** — read [README.md](../README.md) for the intended usage and setup notes.
2. **Startup path** — open [CurrencyConverter.java](../../src/main/java/com/github/blaxk3/converter/CurrencyConverter.java) to see how the app launches.
3. **UI and interaction flow** — read [UI.java](../../src/main/java/com/github/blaxk3/ui/UI.java) to understand the screen, events, and validation.
4. **Network and config layer** — finish with [CurrencyRateAPI.java](../../src/main/java/com/github/blaxk3/api/CurrencyRateAPI.java) and [config.properties](../../src/main/resources/config.properties).

## Key Entry Points

- [CurrencyConverter.java](../../src/main/java/com/github/blaxk3/converter/CurrencyConverter.java) — application entry point. `main()` opens the UI on the Swing event thread.
- [UI.java](../../src/main/java/com/github/blaxk3/ui/UI.java) — main frame, user actions, amount validation, currency selection, and button handlers.
- [CurrencyRateAPI.java](../../src/main/java/com/github/blaxk3/api/CurrencyRateAPI.java) — loads the API key, builds request URLs, fetches currency codes, and performs conversions.

## Project Structure

The repository is organized by responsibility rather than by feature slice:

- `src/main/java/com/github/blaxk3/converter/` — application bootstrap and launch code.
- `src/main/java/com/github/blaxk3/ui/` — Swing window, widgets, listeners, and input filtering.
- `src/main/java/com/github/blaxk3/api/` — HTTP client logic for ExchangeRate-API.
- `src/main/resources/` — runtime resources such as configuration and app icons.

There are no deep module trees or framework layers here, so most changes will happen in one of the three classes above.

## Configuration

- [pom.xml](../../pom.xml) controls the build and dependencies.
  - Java source/target is set to **23**.
  - Dependencies include **Gson** for JSON parsing and **SLF4J** for logging.
- [config.properties](../../src/main/resources/config.properties) stores the `API_KEY` used by the exchange-rate client.
  - Replace `YOUR_API_KEY` with your real ExchangeRate-API key before running the app.
  - If this file is missing, the app logs an error and cannot fetch rates.

## Common Patterns

- **Single-responsibility classes**: launch, UI, and API access are kept separate.
- **SwingWorker for background loading**: currency codes are fetched asynchronously so the UI does not freeze during network calls.
- **Input filtering**: the amount field uses a `DocumentFilter` to allow numeric input with one decimal point.
- **Logging over silent failure**: network and configuration errors are reported with SLF4J.
- **Simple data flow**: the UI reads selections and amount, calls the API client, then formats the result for display.

## Where to Go Next

After you understand the startup path, follow one user action all the way through: pick the **Convert** button in [UI.java](../../src/main/java/com/github/blaxk3/ui/UI.java), trace the call into [CurrencyRateAPI.java](../../src/main/java/com/github/blaxk3/api/CurrencyRateAPI.java), and then look at how the response is formatted back in the UI. That loop explains most of the codebase.