---
title: Ceylon Gold Rate
emoji: 🪙
colorFrom: yellow
colorTo: red
sdk: docker
app_port: 7860
pinned: false
---

# 🪙 Ceylon Gold Price Tracker (Sri Lanka)

### A premium product of [SS Labz](https://github.com/SadeepSachintha)

A premium, responsive, real-time web application to check and estimate 22K, 24K, 21K, and 18K gold prices in Sri Lanka. It features a sophisticated glassmorphic design, persistent Dark/Light theme toggles, interactive historical trend lines, an intelligent jewelry cost calculator, and a server-side web scraper with automated caching.

Designed for high-performance and seamless hosting locally under XAMPP or in production as a **Docker Space on Hugging Face**.

---

## 🚀 Key Features

*   **Real-Time Scraper Backend (`api.php`)**: Dynamically parses the latest retail gold indexes in Sri Lanka using server-side cURL requests.
*   **4-Hour Caching Layer (`rates_cache.json`)**: Caches scraped JSON datasets to optimize site performance, reduce server loading times (<15ms), and prevent IP address rate limits. Includes automatic expired-cache fallbacks if the internet or source site goes offline.
*   **Automated Scheduled Daily Scraping (GitHub Actions)**: A scheduled daily GitHub Action workflow automatically runs the scraper at 6:00 AM Sri Lankan Time everyday, commits the fresh `rates_cache.json` back to the repository, and auto-deploys it to Hugging Face Spaces. This guarantees visitors always load pre-scraped, instantaneous rates.
*   **Intelligent Value Calculator**: Instantly computes raw base gold prices by converting between Grams and Sovereigns (1 sovereign = 8 grams) and Karats (24K, 22K, 21K, 18K). It allows buyers to input customizable making/wastage charges (0%–100%) to estimate the true retail cost.
*   **Dynamic Trend Charts**: Integrates Chart.js to map up to 50 days of real, parsed historical prices. Supports 7D, 30D, and 50D (1Y) period filters with neon gold gradients.
*   **Theme Adaptation Engine**: Seamlessly shifts typography gridlines, card backgrounds, scrollbars, and Chart.js coordinates when toggling between persistent Light and Dark modes.
*   **Sri Lankan Buying Guide**: An accessible, interactive accordion answering common questions about purchasing gold locally, hallmarks, and verifying purity.
*   **Hugging Face CI/CD Ready**: Includes a production `Dockerfile` configured to route container traffic through Hugging Face's port `7860` and a GitHub Actions deploy pipeline.

---

## 🛠️ Project Structure

```
Ceylon Gold Rate/
├── .github/
│   └── workflows/
│       ├── deploy.yml        # CI/CD pipeline to sync repository pushes to Hugging Face
│       └── scrape.yml        # Scheduled daily gold scraper workflow
├── index.html                # Semantic, SEO-optimized markup
├── style.css                 # Premium custom variables, layouts, animations, and typography
├── app.js                    # Client-side reactivity, conversions, calculators, and charts
├── api.php                   # cURL scraper parsing current and historical rates
├── Dockerfile                # Configures Apache, PHP-cURL, and port 7860 for Hugging Face
└── README.md                 # Project guide and documentation
```

---

## 💻 Local Installation (XAMPP)

1.  **Move the Files**: Copy the entire project directory into your XAMPP's document root folder:
    `C:\xampp\htdocs\Ceylon Gold Rate\` (or `D:\xampp\htdocs\Ceylon Gold Rate\`).
2.  **Start the Server**: Open the **XAMPP Control Panel** and click **Start** next to the **Apache** module.
3.  **Open in Browser**: Navigate to:  
    👉 **[http://localhost/Ceylon%20Gold%20Rate/](http://localhost/Ceylon%20Gold%20Rate/)**
4.  **Scrape Live Data**: Click **Refresh Market Rates** to trigger the cURL parser and load real-time prices instantly!

---

## 🐳 Hugging Face Spaces Deployment

Since the application requires a backend server-side scraper (`api.php`), you cannot deploy it as a static space. Instead, deploy it as a **Docker Space**:

1.  Log in to **Hugging Face** and click **Create new Space**.
2.  Set your Space name to `Ceylon-Gold-Rate`.
3.  Select **Docker** as the SDK (Important!), and select the **Blank** template.
4.  Upload the following files from your local workspace:
    *   `index.html`
    *   `style.css`
    *   `app.js`
    *   `api.php`
    *   `Dockerfile`
5.  Hugging Face will automatically compile the Docker container, spin up PHP 8.2-Apache, direct port mapping to `7860`, and host your dashboard live!

---

## 🔄 Automated CI/CD Setup (GitHub Actions)

You can sync pushes to your GitHub repository automatically to your Hugging Face Space using the pre-configured workflow:

1.  **Generate HF Token**:
    *   On Hugging Face, go to **Settings** -> **Access Tokens**.
    *   Generate a new token named `github-sync` with **Write** privileges. Copy it.
2.  **Add Secret to GitHub**:
    *   Go to your GitHub repository -> **Settings** -> **Secrets and variables** -> **Actions** -> **New repository secret**.
    *   Set the name to `HF_TOKEN` and paste your Hugging Face token.
3.  **Confirm Target URL**:
    *   Confirm your repository path inside `.github/workflows/deploy.yml` is set correctly:
        `git remote add hf https://dwssp:$HF_TOKEN@huggingface.co/spaces/dwssp/Ceylon-Gold-Rate`
4.  **Push to GitHub**:
    *   Push your changes to GitHub (`main` or `master` branch) to trigger the Actions sync and deploy automatically!

---

## ⏰ Automated Scheduled Daily Scraping

The project is pre-configured with a daily scraper workflow (`.github/workflows/scrape.yml`) that runs automatically every day at 6:00 AM Sri Lankan Time (00:30 UTC).

### How it Works:
1. **GitHub Action Scheduled Trigger**: The workflow wakes up daily and spins up a temporary PHP environment.
2. **Scraper Execution**: It executes `api.php` via PHP CLI, generating a fresh, fully parsed `rates_cache.json`.
3. **Automated Commit**: It automatically commits the updated `rates_cache.json` back to the GitHub repository's `main` branch.
4. **Auto-Deployment**: Pushing to the `main` branch automatically triggers `deploy.yml`, which deploys the freshly cached rates to Hugging Face Spaces!

### Setup Requirement (Important):
To allow the daily scraper to commit updates back to your repository:
1. Go to your GitHub repository **Settings** -> **Actions** -> **General**.
2. Scroll down to the **Workflow permissions** section.
3. Select **Read and write permissions**.
4. Click **Save**.