# Repository Overview

Welcome to the Currency Converter project! This is a Java desktop application that lets users convert amounts between different currencies using live exchange-rate data. Built with Java Swing for the graphical interface and backed by the [ExchangeRate API v6](https://www.exchangerate-api.com/) for real-time rates, the application is designed to be simple, responsive, and easy to extend. If you're a new team member, this page will orient you to what the code does, how it's structured, and where to start reading.

---

## Overview

This repository implements a **desktop Currency Converter** application in Java. The user enters an amount, selects a source and target currency, and clicks "Convert" to see the result fetched from a live exchange-rate service. The app also provides a "Swap" button to reverse the conversion direction and a "Clear" button to reset the form.

The project is organized into three top-level packages:

| Package | Purpose |
|---------|---------|
| `com.github.blaxk3.api` | HTTP client wrapping the ExchangeRate API v6 |
| `com.github.blaxk3.converter` | Application entry point |
| `com.github.blaxk3.ui` | Swing-based desktop interface |

No well-known frameworks were detected from import analysis beyond the standard Java libraries, Gson, and SLF4J — the project leans on plain Java (JDK) and its built-in Swing GUI toolkit.

---

## Technology Stack

| Technology | Role |
|------------|------|
| **Java** (JDK) | Core language; `java.math.BigDecimal` for monetary precision |
| **Java Swing / AWT** | Desktop GUI framework (`JFrame`, `JPanel`, `JButton`, `JComboBox`, etc.) |
| **Gson** (`com.google.gson`) | JSON parsing of ExchangeRate API responses |
| **SLF4J** (`org.slf4j`) | Structured logging across modules |
| **ExchangeRate API v6** | External REST service providing live currency codes and conversion rates |

---

## Architecture

The application follows a clean three-tier structure: the **entry point** launches the **GUI layer**, which delegates data fetching to the **API client**, which in turn calls the external ExchangeRate service over HTTP.

```mermaid
flowchart TD
    Converter["CurrencyConverter
(Entry Point)"] -->|"launches on EDT"| UI["UI
(Swing Desktop GUI)"]
    UI --> API["CurrencyRateAPI
(Exchange Rate Client)"]
    API -->|"HTTP GET"| ExternalAPI["External Exchange Rate API"]
    UI -->|"input validation"| NF["NumericFilter"]
    UI -->|"background fetch"| CC["CurrencyCode
(SwingWorker)"]
    CC --> API
```

**How it works, at a glance:**

1. **`CurrencyConverter.main`** starts the JVM entry point and schedules the UI construction on the Swing Event Dispatch Thread (EDT).
2. **`UI`** builds the window, creates all components, and starts background workers to populate the currency dropdowns.
3. **`CurrencyCode`** (a `SwingWorker`) fetches available currency codes from the API off the EDT, keeping the interface responsive.
4. When the user clicks **Convert**, the UI calls `CurrencyRateAPI.convert(...)` to get the live rate and displays the result.

---

## Module Guide

### `com.github.blaxk3.api` — CurrencyRateAPI

This module is a thin HTTP client wrapper around the [ExchangeRate API v6](https://www.exchangerate-api.com/). It owns everything needed to communicate with the remote service: API-key loading from `config.properties`, URL assembly, HTTP GET requests, and JSON response parsing via Gson.

The sole class in this package is:

- **`CurrencyRateAPI`** — The only class in the package. Provides `getApiKeyService()` to load the API key from `config.properties`, `getURL()` to assemble the authenticated base URL, `getJsonObject(URL)` to perform an HTTP GET and parse the JSON response, `getCurrencyCode()` to retrieve the full list of supported ISO 4217 currency codes, and `convert(from, to, amount)` to fetch the exchange rate for a given pair and amount. All methods are self-contained; the class holds no mutable instance state, making it thread-safe.

### `com.github.blaxk3.converter` — CurrencyConverter

This module is the application entry point. It contains a single class with a single method whose only job is to launch the GUI.

- **`CurrencyConverter`** — Contains the `main(String[] args)` method. Calls `SwingUtilities.invokeLater(UI::new)` to bootstrap the application on the Swing EDT. No conversion logic or UI code lives here.

### `com.github.blaxk3.ui` — UI, NumericFilter, CurrencyCode

This module is the presentation layer — everything the user sees and interacts with. It builds a single `JFrame` window containing an input field, two currency dropdowns, a result label, and three action buttons.

- **`UI`** (extends `JFrame`) — The main application window. Creates the layout (a two-column grid with dark gray sub-panels), wires up all Swing components, and registers button listeners. Handles "Convert" (fetches and displays the result), "Swap" (exchanges the two currency selections), and "Clear" (resets the form). Uses factory methods (`comboBox1()`, `comboBox2()`, `button()`, `textField()`, `label()`) to keep component creation encapsulated.
- **`NumericFilter`** — A `DocumentFilter` installed on the amount text field. Allows only digits and at most one decimal point, preventing invalid input at the keystroke level.
- **`CurrencyCode`** — A `SwingWorker` that fetches available currency codes from `CurrencyRateAPI.getCurrencyCode()` in the background, then sorts and populates the dropdowns on the EDT when complete. One instance is created per combo box, so both dropdowns populate independently and in parallel.

---

## Getting Started

If you've just cloned this repository and want to understand the codebase, here is a recommended reading order:

1. **`src/main/java/com/github/blaxk3/converter/CurrencyConverter.java`** — Start here. This 3-line entry point tells you how the application launches and hands off to the UI.
2. **`src/main/java/com/github/blaxk3/ui/UI.java`** — Read the main window class next. Walk through the constructor and the `panel()` layout builder to understand the visual structure. Then read the button listener implementations and the nested `NumericFilter` and `CurrencyCode` classes.
3. **`src/main/java/com/github/blaxk3/api/CurrencyRateAPI.java`** — Finally, read the API client to understand how exchange-rate data is fetched and parsed.

### Before you run

Make sure you have an API key for the ExchangeRate API v6 and place it in a file named `config.properties` on the application classpath:

```properties
API_KEY=your_api_key_here
```

### Key entry points to keep in mind

| Class | Role |
|-------|------|
| `CurrencyConverter.main()` | JVM entry point; launches the app |
| `UI` constructor | Builds and displays the window |
| `CurrencyRateAPI.convert()` | Performs the actual currency conversion |
| `CurrencyCode.doInBackground()` | Fetches currency codes in the background |
| `NumericFilter.isValid()` | Validates amount input at the character level |