Currency Converter - Project Plan

Goal

Build a single-page currency converter web application that enables users to convert between seven major world currencies: Australian Dollar (AUD), US Dollar (USD), Canadian Dollar (CAD), British Pound (GBP), Euro (EUR), Japanese Yen (JPY), and Chinese Yuan (CNY). The application will fetch real-time exchange rates from a free external API and provide instant conversion calculations in a clean, usable interface. All code will be contained within a single HTML file incorporating HTML, CSS, and JavaScript with minimal dependencies. The application will intelligently detect the user's location to set appropriate defaults and persist user preferences across sessions.

Requirements

• MUST support conversion between all seven currencies: AUD, USD, CAD, GBP, EUR, JPY, CNY
• MUST fetch current exchange rates from a free API without requiring an API key
• MUST provide an input field for the amount to convert
• MUST provide dropdown selectors for both source and target currencies
• MUST display the converted result with appropriate decimal formatting
• MUST handle API errors gracefully with user-friendly error messages
• MUST detect local country from user and if it is in From list, must default to that
• MUST always remember the last amount, from and to you set (localStorage persistence)
• MUST provide a share link which saves amount, from and to (URL query parameters)
• SHOULD display the last updated timestamp for exchange rates
• SHOULD include a swap button to reverse source and target currencies
• SHOULD cache exchange rates locally to minimise API calls (valid for the session)

Research

• ExchangeRate-API (exchangerate-api.com) offers an open access endpoint at https://api.exchangerate-api.com/v4/latest/{base} that requires no API key and returns JSON data suitable for personal and commercial use with attribution
• exchangerate.host provides a completely free REST API with real-time rates for 168+ currencies, no API key required, and returns data in JSON format
• IP Geolocation: IP detection services like ipapi.co can detect user country code from IP address for currency default selection
• Timezone fallback: Intl.DateTimeFormat().resolvedOptions().timeZone can be used as fallback to guess user location when IP detection fails
• Country to Currency mapping: AU→AUD, US→USD, CA→CAD, GB→GBP, EU→EUR (or individual EU countries), JP→JPY, CN→CNY
• Currency precision standards: JPY typically displays 0 decimal places, while AUD, USD, CAD, GBP, EUR, and CNY display 2 decimal places
• API endpoints return base currency rates where all values represent the conversion rate from the base currency to the target currency
• Free APIs typically update rates once per day (daily rates) rather than true real-time market rates
• URLSearchParams API provides easy query string manipulation for share link functionality
• localStorage persists data indefinitely until cleared by user

Phases

Phase 1: Core Conversion Functionality

• Create HTML structure with single-file layout (HTML, CSS, JS combined)
• Implement CSS styling with Helvetica font, 16px inputs, minimal box-sizing reset
• Build amount input field with number type validation
• Build source and target currency dropdowns populated with the 7 supported currencies
• Integrate with ExchangeRate-API open access endpoint to fetch latest rates
• Implement conversion calculation logic using fetched rates
• Display converted result with proper formatting (2 decimals for most, 0 for JPY)
• Add error handling for network failures or API unavailability

Phase 2: Persistence & Defaults

• Implement localStorage persistence for amount, from, and to selections
• Implement URL query parameter parsing for share links (amount, from, to)
• Implement IP-based country detection to set default "from" currency
• Add timezone-based fallback detection if IP detection fails
• Ensure priority: URL params > localStorage > IP detection > USD default

Phase 3: UI/UX Enhancements

• Add swap button functionality to exchange source and target currencies
• Display last updated timestamp from API response
• Add loading indicator during API fetch
• Implement localStorage caching for exchange rates (refresh only if older than 1 hour)
• Add share button that generates URL with current parameters and copies to clipboard
• Add keyboard support (Enter key triggers conversion)

Phase 4: Additional Features

• Add quick-select buttons for common conversion pairs
• Display inverse exchange rate (1 target = X source)
• Add copy-to-clipboard functionality for the converted amount