# Repository Overview

Welcome to the **Currency Converter** application! This is a desktop GUI program written in Java that lets you enter an amount and instantly convert it between any two currencies using live foreign exchange rates. It is built on the **Java Swing** UI toolkit, fetches real-time data from the **exchangerate-api.com** service, and presents everything through a clean, simple window. Whether you're here to maintain the codebase, add new features, or just get familiar with how the pieces fit together — you're in the right place.

---

## Overview

This project is a **Java Swing desktop application** for real-time currency conversion. The user enters a monetary amount and selects a source and target currency from dropdown menus, then clicks **Convert** to see the result. Behind the scenes, the app reaches out to [exchangerate-api.com](https://www.exchangerate-api.com/) to fetch live exchange rates, handling all network communication and JSON parsing transparently.

The application is organized into three packages:

| Package | Purpose |
|---------|---------|
| `com.github.blaxk3.converter` | Application entry point (`main` method) |
| `com.github.blaxk3.ui` | The Swing GUI window and its components |
| `com.github.blaxk3.api` | HTTP client for the exchange rate API |

---

## Technology Stack

| Technology | Role |
|------------|------|
| **Java Swing** | Desktop GUI framework (JFrame, JPanel, JButton, JComboBox, JTextField, etc.) |
| **exchangerate-api.com** | External REST service providing live foreign exchange rates |
| **Gson** | JSON parsing library for deserializing API responses |
| **SLF4J** | Logging facade for error reporting |
| **BigDecimal** | Precision-preserving monetary arithmetic |
| **SwingWorker** | Background thread execution for non-blocking API calls |
| **DocumentFilter** | Input validation for the amount text field |

No well-known application frameworks (such as Spring or JavaFX) were detected — this project is a straightforward standard-Java-SE application using only the JDK standard library and the two external dependencies above.

---

## Architecture

The application follows a simple **launcher → UI → API** pipeline:

```mermaid
flowchart TD
    Converter["CurrencyConverter
Launcher"] --> UI["UI
Swing GUI"]
    UI --> API["CurrencyRateAPI
Exchange rate client"]
    UI --> Swing["Java Swing
GUI framework"]
    API --> Gson["Gson
JSON parser"]
    API --> Config["config.properties
API key"]
```

1. **`CurrencyConverter`** (launcher) starts the JVM and schedules the `UI` constructor on the Swing Event Dispatch Thread.
2. **`UI`** builds the window, creates the input components (amount field, currency dropdowns, action buttons), and launches background `SwingWorker` tasks to populate the currency lists.
3. **`CurrencyRateAPI`** (client) reads the API key from `config.properties`, opens HTTP connections to exchangerate-api.com, and returns parsed results via Gson.

---

## Module Guide

### `com.github.blaxk3.converter` — Application Launcher

This package contains the single entry point for the application: the `CurrencyConverter` class. It does not hold any logic beyond calling `SwingUtilities.invokeLater(UI::new)` to bootstrap the GUI on the correct Swing thread. All business logic and rendering live in the `ui` module.

**Key class:**
- **`CurrencyConverter`** — Thin launcher that starts the Java Swing application.

### `com.github.blaxk3.ui` — Graphical Interface

This package is the heart of the user experience. The `UI` class extends `JFrame` and assembles the entire application window: a text field for entering amounts, two dropdown menus for selecting currencies, and three action buttons (**Convert**, **Swap**, **Clear**). It also includes a custom `DocumentFilter` (`NumericFilter`) that restricts the amount field to digits and at most one decimal point, and a `SwingWorker` subclass (`CurrencyCode`) that fetches available currencies from the API in the background without blocking the UI thread.

**Key classes:**
- **`UI`** — The main application window. Handles layout, event listeners, and ties together the text field, combo boxes, and buttons.
- **`NumericFilter`** — A `DocumentFilter` that validates user input in the amount field (digits and optional single period).
- **`CurrencyCode`** — A `SwingWorker` that fetches currency codes from `CurrencyRateAPI` on a background thread and populates a combo box on the EDT.

### `com.github.blaxk3.api` — Exchange Rate Client

This package provides the `CurrencyRateAPI` class, which is a thin HTTP client for the exchangerate-api.com REST service. It handles API key loading from `config.properties`, URL assembly, HTTP GET requests via `HttpURLConnection`, and JSON response parsing via Gson. It exposes two primary operations: listing all supported ISO 4217 currency codes and performing a conversion between two currencies given an amount.

**Key class:**
- **`CurrencyRateAPI`** — The sole class in the package. It loads the API key, builds requests to `https://v6.exchangerate-api.com/v6/`, and returns parsed currency data and conversion results.

---

## Getting Started

If you are new to this codebase and want to understand how it works end to end, follow this reading order:

1. **`src/main/java/com/github/blaxk3/converter/CurrencyConverter.java`** — The entry point. Two lines of code that show how the application boots.
2. **`src/main/java/com/github/blaxk3/ui/UI.java`** — The largest and most interesting file. Read the constructor and `panel()` method to understand the layout, then follow the `ActionListener` attached to the **Convert** button to see how a conversion is triggered.
3. **`src/main/java/com/github/blaxk3/api/CurrencyRateAPI.java`** — The HTTP client. Read this to understand how exchange rates are fetched and how JSON responses are parsed.
4. **`config.properties`** (expected at `src/main/resources/config.properties`) — A single-line configuration file that holds your exchangerate-api.com API key. Without this, the application cannot fetch live data.

### Running the application

```bash
mvn package
java -jar target/currency-converter.jar
```

Or, using an IDE, run `CurrencyConverter.main(String[])` directly from your IDE's run configuration.

### Key files at a glance

| File | Description |
|------|-------------|
| `src/main/java/com/github/blaxk3/converter/CurrencyConverter.java` | Application launcher |
| `src/main/java/com/github/blaxk3/ui/UI.java` | GUI window and all UI logic |
| `src/main/java/com/github/blaxk3/api/CurrencyRateAPI.java` | API client for exchange rates |
| `src/main/resources/config.properties` | Configuration (API key) |

---

*Last updated: June 2026*