# Getting Started

Welcome to the Currency Converter project. This guide will help you hit the ground running.

## What This Project Does

This is a desktop currency converter that fetches live exchange rates from [ExchangeRate-API](https://www.exchangerate-api.com) and lets users convert between any supported currencies via a Swing GUI. It runs as a single executable application built with Java 23 and Maven.

## Recommended Reading Order

1. [README.md](../README.md) -- project overview, requirements, and quick start
2. [src/main/java/com/github/blaxk3/converter/CurrencyConverter.java](../src/main/java/com/github/blaxk3/converter/CurrencyConverter.java) -- the entry point; 11 lines that launch the app
3. [src/main/java/com/github/blaxk3/ui/UI.java](../src/main/java/com/github/blaxk3/ui/UI.java) -- the main Swing window with input fields, buttons, and result display
4. [src/main/java/com/github/blaxk3/api/CurrencyRateAPI.java](../src/main/java/com/github/blaxk3/api/CurrencyRateAPI.java) -- the API client that talks to ExchangeRate-API
5. [src/main/resources/config.properties](../src/main/resources/config.properties) -- where your API key lives

## Key Entry Points

| Class | Path | Why it matters |
|---|---|---|
| `CurrencyConverter` | [CurrencyConverter.java](../src/main/java/com/github/blaxk3/converter/CurrencyConverter.java) | Application entry point. Calls `SwingUtilities.invokeLater(UI::new)` to start the GUI on the EDT. |
| `UI` | [UI.java](../src/main/java/com/github/blaxk3/ui/UI.java) | The main window. Contains the text field, two currency dropdowns, Convert/Swap/Clear buttons, and two inner classes (`NumericFilter` for input validation, `CurrencyCode` for background currency-code fetching). |
| `CurrencyRateAPI` | [CurrencyRateAPI.java](../src/main/java/com/github/blaxk3/api/CurrencyRateAPI.java) | HTTP client wrapping the ExchangeRate-API v6 REST endpoint. Handles API key loading, JSON parsing with Gson, and exposes `getCurrencyCode()` and `convert()`. |

## Project Structure

```
pom.xml
src/main/java/com/github/blaxk3/
  api/
    CurrencyRateAPI.java      # REST client for exchange rates
  converter/
    CurrencyConverter.java     # Main class (entry point)
  ui/
    UI.java                    # Swing GUI window + helpers
src/main/resources/
  config.properties            # API key configuration
  icon/image/icon.png          # Window icon
```

Three packages, three files. The code is organized by concern: `api` (data fetching), `converter` (bootstrap), `ui` (user interface).

## Architecture

```mermaid
flowchart TD
    Start["Main: CurrencyConverter"] --> UI["UI Swing Window"]
    UI --> FetchCode["Background: CurrencyCode SwingWorker"]
    UI --> Convert["User clicks Convert"]
    FetchCode --> API["CurrencyRateAPI"]
    Convert --> API
    API --> JSON["ExchangeRate-API v6"]
```

1. `CurrencyConverter.main()` creates and shows a `UI` window on the Swing EDT.
2. `UI` constructor launches two `CurrencyCode` SwingWorkers in parallel to populate the "from" and "to" currency dropdowns by calling `CurrencyRateAPI.getCurrencyCode()`.
3. When the user types an amount, selects two currencies, and clicks **Convert**, the UI calls `CurrencyRateAPI.convert()` which hits the ExchangeRate-API `/pair/<from>/<to>/<amount>` endpoint.
4. The result is formatted with a `DecimalFormat` and displayed in the label.

## Configuration

**`src/main/resources/config.properties`** -- holds your [ExchangeRate-API](https://www.exchangerate-api.com) key:

```properties
API_KEY = YOUR_API_KEY
```

This file is loaded by `CurrencyRateAPI.getApiKeyService()` at runtime using `java.util.Properties`. The key is then appended to the base URL to build the full endpoint: `https://v6.exchangerate-api.com/v6/<YOUR_KEY>`.

Get a free API key at [https://www.exchangerate-api.com/](https://www.exchangerate-api.com/).

**`pom.xml`** -- Maven build descriptor. Key details:
- Java 23 (`maven.compiler.source` / `target`)
- Dependencies: Gson 2.12.1 (JSON parsing), SLF4J 2.0.17 (logging)

## Common Patterns

- **EDT discipline**: The GUI is always created on the Event Dispatch Thread via `SwingUtilities.invokeLater()`.
- **Background fetching**: Long-running HTTP calls are done in `SwingWorker` subclasses (`CurrencyCode`) so the UI stays responsive.
- **Input validation**: A `DocumentFilter` (`NumericFilter`) ensures only valid numeric input (digits and at most one decimal point) reaches the text field.
- **Error logging**: All exceptions are logged via SLF4J; failures from the API surface as `null` returns or thrown exceptions rather than crashes.
- **Immutable constants**: Logger instances and formatting patterns are `private static final`.

## Running the App

```bash
# 1. Set your API key in config.properties
# 2. Build and run
mvn -q compile exec:java -Dexec.mainClass="com.github.blaxk3.converter.CurrencyConverter"
```

You need **JDK 23+** to compile and run this project.

## Dependencies

| Library | Purpose |
|---|---|
| Gson 2.12.1 | Parsing JSON responses from ExchangeRate-API |
| SLF4J API + Simple 2.0.17 | Structured logging to stdout |

No other external dependencies. Everything is managed through Maven.