# Getting Started

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

## What This Project Does

This is a **desktop currency converter** built in Java with a Swing GUI. It fetches live exchange rates from the free [ExchangeRate-API](https://www.exchangerate-api.com) and converts amounts between any supported currencies. Users enter an amount, select a source and target currency, and get an instant conversion — with support for swapping currencies or clearing the form.

## Recommended Reading Order

Start here to build a mental model quickly:

1. **[README](../README.md)** — Project overview, requirements (JDK 23+), and quick usage instructions.
2. **[`CurrencyConverter.java`](../src/main/java/com/github/blaxk3/converter/CurrencyConverter.java)** — The 4-line entry point. Understand how the app boots.
3. **[`UI.java`](../src/main/java/com/github/blaxk3/ui/UI.java)** — The entire GUI: layout, input validation, buttons, and the background task that loads currency codes.
4. **[`CurrencyRateAPI.java`](../src/main/java/com/github/blaxk3/api/CurrencyRateAPI.java)** — The API layer: reading the config, building URLs, and parsing JSON responses.
5. **[`config.properties`](../src/main/resources/config.properties)** — Where you plug in your free API key.

## Key Entry Points

These three classes are the backbone of the application:

- **[`CurrencyConverter.java`](../src/main/java/com/github/blaxk3/converter/CurrencyConverter.java)** — The `main` method. All it does is hand off to the Swing Event Dispatch Thread (`SwingUtilities.invokeLater(UI::new)`). This is where you start when tracing execution.
- **[`UI.java`](../src/main/java/com/github/blaxk3/ui/UI.java)** — The main window. Contains the layout, two currency combo boxes, an amount text field with numeric-only input validation (`NumericFilter`), Convert/Swap/Clear buttons, and an inner `SwingWorker` (`CurrencyCode`) that fetches available currency codes on startup.
- **[`CurrencyRateAPI.java`](../src/main/java/com/github/blaxk3/api/CurrencyRateAPI.java)** — The API client. Reads `API_KEY` from `config.properties`, builds requests to the ExchangeRate-API endpoint, and provides two public methods: `getCurrencyCode()` (list all supported currency codes) and `convert()` (convert a specific amount between two currencies).

## Project Structure

```
pom.xml
src/main/java/com/github/blaxk3/
  api/
    CurrencyRateAPI.java    # API communication layer
  converter/
    CurrencyConverter.java  # Application entry point (main)
  ui/
    UI.java                 # Swing GUI and input handling
src/main/resources/
  config.properties         # API key configuration
  icon/
    image/
      icon.png              # Window icon
```

Three packages, three responsibilities: **entry point** → **UI** → **API**. No frameworks, no dependency injection — straightforward and easy to trace.

## Configuration

### `config.properties`

Located at `src/main/resources/config.properties`. It has a single required property:

```properties
API_KEY = YOUR_API_KEY
```

**To run the app:**

1. Sign up for a free API key at [https://www.exchangerate-api.com](https://www.exchangerate-api.com).
2. Replace `YOUR_API_KEY` in `config.properties` with your actual key.
3. Build and run.

### `pom.xml`

Key build details:

- **Java 23** — both compiler source and target are set to 23.
- **Dependencies:**
  - `gson 2.12.1` — parsing JSON responses from the exchange rate API.
  - `slf4j-api` + `slf4j-simple` — logging (error and debug output).

To build and run:

```bash
mvn clean package
java -jar target/Currency-Converter-2025.03.20.jar
```

Or run directly from source:

```bash
mvn exec:java -Dexec.mainClass="com.github.blaxk3.converter.CurrencyConverter"
```

## Common Patterns

### Swing concurrency

The UI always runs on the **Swing Event Dispatch Thread**. Background work (fetching currency codes) uses `SwingWorker<String[], Void>` — the `CurrencyCode` inner class. This keeps the UI responsive during the network call.

### Input validation

A custom `DocumentFilter` (`NumericFilter`) restricts the amount text field to digits and at most one decimal point. Non-numeric input is silently rejected.

### Error handling

- Missing or malformed `config.properties` is logged via SLF4J and returns `null` from `getApiKeyService()`.
- Failed HTTP requests log the response code and return `null`, which the UI propagates as an empty combo box.
- The Convert button catches `MalformedURLException` and `URISyntaxException` and wraps them in `RuntimeException`.

## Architecture Overview

Here's how the three core components interact:

```mermaid
flowchart TD
    Start["Start (Java CLI)"] --> Converter["CurrencyConverter.main()"]
    Converter --> EDT["Swing EDT.invokeLater(UI::new)"]
    EDT --> UI["UI (Swing Window)"]
    UI --> Load["CurrencyCode.doInBackground()"]
    Load --> API["CurrencyRateAPI.getCurrencyCode()"]
    API --> Fetch["HTTP GET /latest/USD"]
    Fetch --> Parse["Gson JSON parsing"]
    Parse --> Populated["UI populated with currency codes"]

    UI --> ConvertBtn["User clicks Convert"]
    ConvertBtn --> ConvertAPI["CurrencyRateAPI.convert()"]
    ConvertAPI --> PairRequest["HTTP GET /pair/{from}/{to}/{amount}"]
    PairRequest --> PairParse["Gson JSON parsing"]
    PairParse --> Result["Result displayed in label"]
```

## Prerequisites

- **JDK 23 or higher** — required to compile and run. Download from [jdk.java.net/23](https://jdk.java.net/23/).
- **Maven** — for building the project.
- **A free ExchangeRate-API key** — from [https://www.exchangerate-api.com](https://www.exchangerate-api.com).

## Troubleshooting

- **"Unable to find config.properties"** — The file must be on the classpath (it ships with `src/main/resources`, which Maven copies to `target/classes` automatically).
- **API returns null / empty currencies** — Double-check your `API_KEY` in `config.properties`. An invalid key causes the API to respond with a non-200 status.
- **Build fails with JDK errors** — Ensure your `JAVA_HOME` points to JDK 23+. Run `java -version` to verify.