# Getting Started

## What This Project Does

This is a small Java desktop app for currency conversion. It launches a Swing UI where users enter an amount, pick two currencies, and request a live conversion from the ExchangeRate API. The codebase is intentionally lightweight: one class boots the app, one class owns the UI, and one class handles API calls and configuration.

## Recommended Reading Order

1. **[`README.md`](../README.md)** — get the high-level product context and any usage notes.
2. **[`src/main/java/com/github/blaxk3/converter/CurrencyConverter.java`](../../src/main/java/com/github/blaxk3/converter/CurrencyConverter.java)** — see how the app starts.
3. **[`src/main/java/com/github/blaxk3/ui/UI.java`](../../src/main/java/com/github/blaxk3/ui/UI.java)** — understand the window, user actions, and input handling.
4. **[`src/main/java/com/github/blaxk3/api/CurrencyRateAPI.java`](../../src/main/java/com/github/blaxk3/api/CurrencyRateAPI.java)** — learn how configuration and remote currency data are fetched.
5. **[`src/main/resources/config.properties`](../../src/main/resources/config.properties)** — check the runtime configuration required for API access.

## Key Entry Points

- [`com.github.blaxk3.converter.CurrencyConverter`](../../src/main/java/com/github/blaxk3/converter/CurrencyConverter.java) — the `main` method and startup boundary.
- [`com.github.blaxk3.ui.UI`](../../src/main/java/com/github/blaxk3/ui/UI.java) — the main Swing frame and interaction flow.
- [`UI.NumericFilter`](../../src/main/java/com/github/blaxk3/ui/UI.java) — restricts the amount field to numeric input.
- [`UI.CurrencyCode`](../../src/main/java/com/github/blaxk3/ui/UI.java) — loads currency codes in the background.
- [`com.github.blaxk3.api.CurrencyRateAPI`](../../src/main/java/com/github/blaxk3/api/CurrencyRateAPI.java) — reads config, calls the API, and parses JSON.

```mermaid
flowchart TD
Launcher["com.github.blaxk3.converter.CurrencyConverter"] --> UI["com.github.blaxk3.ui.UI"]
UI --> API["com.github.blaxk3.api.CurrencyRateAPI"]
API --> ExchangeRate["ExchangeRate API"]
UI --> NumericFilter["UI.NumericFilter"]
UI --> CurrencyCode["UI.CurrencyCode"]
```

## Project Structure

The source layout is small and easy to scan:

- [`src/main/java/com/github/blaxk3/converter/`](../../src/main/java/com/github/blaxk3/converter/) — application bootstrap code.
- [`src/main/java/com/github/blaxk3/ui/`](../../src/main/java/com/github/blaxk3/ui/) — Swing UI, actions, and input validation.
- [`src/main/java/com/github/blaxk3/api/`](../../src/main/java/com/github/blaxk3/api/) — HTTP requests, JSON parsing, and API integration.
- [`src/main/resources/`](../../src/main/resources/) — runtime resources such as `config.properties` and icons.

There is no deep module hierarchy here, so most onboarding time should go to the three classes above rather than to framework setup.

## Configuration

The key configuration file is [`src/main/resources/config.properties`](../../src/main/resources/config.properties).

- `API_KEY` is required by [`CurrencyRateAPI`](../../src/main/java/com/github/blaxk3/api/CurrencyRateAPI.java).
- The API client builds requests against `https://v6.exchangerate-api.com/v6/` and appends the key from this file.
- If `config.properties` is missing or the key is blank, currency lookups and conversions will fail.

The build file, [`pom.xml`](../../pom.xml), shows the project is targeting Java 23 and depends on:

- **Gson** for JSON parsing
- **SLF4J** for logging
- **SLF4J Simple** for a basic logging backend

## Common Patterns

- **Thin launcher, rich UI**: [`CurrencyConverter`](../../src/main/java/com/github/blaxk3/converter/CurrencyConverter.java) only starts Swing and hands control to the UI.
- **Background loading for responsiveness**: [`UI.CurrencyCode`](../../src/main/java/com/github/blaxk3/ui/UI.java) uses `SwingWorker` so currency lists load without freezing the window.
- **Input guarding at the field level**: [`UI.NumericFilter`](../../src/main/java/com/github/blaxk3/ui/UI.java) prevents invalid amount input before conversion runs.
- **Direct API wrapper**: [`CurrencyRateAPI`](../../src/main/java/com/github/blaxk3/api/CurrencyRateAPI.java) is a thin client around the external service rather than a large abstraction layer.
- **Simple state held by the frame**: the UI stores its main controls as fields and updates them directly from button handlers.

## Where to Start When You Make a Change

- Need to change startup behavior? Start in [`CurrencyConverter`](../../src/main/java/com/github/blaxk3/converter/CurrencyConverter.java).
- Need to change the form, buttons, or validation? Start in [`UI`](../../src/main/java/com/github/blaxk3/ui/UI.java).
- Need to change API endpoints, request format, or config handling? Start in [`CurrencyRateAPI`](../../src/main/java/com/github/blaxk3/api/CurrencyRateAPI.java).
- Need to change credentials or runtime config? Start in [`config.properties`](../../src/main/resources/config.properties).

If you are brand new to the repository, read the launcher first, then the UI, then the API client. That gives you the shortest path from app startup to user interaction to network behavior.