# Getting Started

## What This Project Does

This project is a desktop currency converter built with Java Swing. It fetches live exchange rates from ExchangeRate-API, lets users pick a source and target currency, and converts an entered amount in the UI.

## Recommended Reading Order

1. **Start with this guide** to understand the app shape and where the main pieces live.
2. **Read [`README.md`](README.md)** for the original project overview, runtime requirements, and setup notes.
3. **Open [`src/main/java/com/github/blaxk3/converter/CurrencyConverter.java`](src/main/java/com/github/blaxk3/converter/CurrencyConverter.java)** to see the application entry point.
4. **Then inspect [`src/main/java/com/github/blaxk3/ui/UI.java`](src/main/java/com/github/blaxk3/ui/UI.java)** to understand the desktop interface and user actions.
5. **Finally review [`src/main/java/com/github/blaxk3/api/CurrencyRateAPI.java`](src/main/java/com/github/blaxk3/api/CurrencyRateAPI.java)** to see how live rates and conversion results are fetched.

## Key Entry Points

There are three core classes in this codebase:

- [`com.github.blaxk3.converter.CurrencyConverter`](src/main/java/com/github/blaxk3/converter/CurrencyConverter.java) — the `main` method and startup entry point.
- [`com.github.blaxk3.ui.UI`](src/main/java/com/github/blaxk3/ui/UI.java) — the Swing window, form controls, actions, and input validation.
- [`com.github.blaxk3.api.CurrencyRateAPI`](src/main/java/com/github/blaxk3/api/CurrencyRateAPI.java) — the API client that loads configuration, requests exchange-rate data, and performs conversions.

## Project Structure

The source layout is small and easy to navigate:

- [`src/main/java/com/github/blaxk3/converter/`](src/main/java/com/github/blaxk3/converter/) contains the app entry point.
- [`src/main/java/com/github/blaxk3/ui/`](src/main/java/com/github/blaxk3/ui/) contains the Swing frame, widgets, and UI behavior.
- [`src/main/java/com/github/blaxk3/api/`](src/main/java/com/github/blaxk3/api/) contains the external API integration.
- [`src/main/resources/`](src/main/resources/) contains runtime resources such as [`config.properties`](src/main/resources/config.properties) and the app icon.

The codebase is intentionally compact, so most onboarding work happens by tracing the flow from startup to UI to API call.

## Configuration

Two files matter most when you are getting set up:

- [`pom.xml`](pom.xml) — defines the Maven project, Java 23 source/target level, and dependencies such as Gson and SLF4J.
- [`src/main/resources/config.properties`](src/main/resources/config.properties) — stores the `API_KEY` used to call ExchangeRate-API.

If conversions are failing, the first thing to check is the API key value in `config.properties` and whether it is available on the classpath at runtime.

## Common Patterns

A few patterns repeat throughout the code:

- **UI startup happens on the Swing event thread.** The app launches the frame with `SwingUtilities.invokeLater(...)`.
- **Network work is kept off the UI thread.** Currency codes are loaded with `SwingWorker` so the window stays responsive.
- **Input is validated before conversion.** The text field uses a `DocumentFilter` to allow only numeric input and one decimal point.
- **Helpers are small and focused.** Each class owns one concern: startup, UI, or API access.
- **Logging uses SLF4J.** Failures are recorded through logger calls rather than printed directly.

## Where To Go Next

After reading the three entry points above, the next useful step is to trace one user flow end-to-end:

1. launch from [`CurrencyConverter`](src/main/java/com/github/blaxk3/converter/CurrencyConverter.java)
2. inspect how [`UI`](src/main/java/com/github/blaxk3/ui/UI.java) builds the window
3. follow the Convert button into [`CurrencyRateAPI`](src/main/java/com/github/blaxk3/api/CurrencyRateAPI.java)

That path will show you almost everything needed to make your first change safely.