README.md

Satu Ramadhan

A beautiful, offline-first Progressive Web App for Ramadhan prayer schedules

---

✨ Features

	Feature	Description
🕌	Accurate Prayer Times	Powered by Aladhan API with Kemenag RI calculation method
📍	GPS & Manual Location	Auto-detect via GPS or select from 500+ Indonesian regencies
🧭	Qibla Compass	Real-time compass with device orientation & magnetic calibration
📅	Full Monthly Schedule	Complete Ramadhan timetable — Imsak, Subuh, Dzuhur, Ashar, Maghrib, Isya
⏱️	Live Countdown	Next prayer countdown timer on the home screen
📱	Installable PWA	Add to home screen for a native app experience
🌙	Offline-First	Works without internet after first visit
🎨	Premium Dark Theme	Elegant teal & gold design with smooth animations
🏢	Multi-Organization	Supports Muhammadiyah (Hisab) and NU/Government (Rukyatul Hilal)

---

🚀 Getting Started

Prerequisites

• Node.js ≥ 18 (for production builds)
• Any static file server for local development

Local Development

# Clone the repository
git clone https://github.com/aleafarrel/saturamadhan.git
cd saturamadhan

# Serve with any static server — for example:
npx serve .
# or
npx http-server .

Open http://localhost:3000 (or whichever port) in your browser.

Production Build

npm install        # Install esbuild
npm run build      # Generate dist/ folder

The build script bundles and minifies all assets:

Asset	Before	After	Reduction
CSS (19 files → 1)	71.3 KB	49.8 KB	30%
JS (10 modules → 1)	188.6 KB	70.7 KB	63%
Total	311.7 KB	156.0 KB	50%

---

🌐 Deployment (GitHub Pages)

This project uses a dist branch for GitHub Pages deployment. The dist branch contains only the minified production build.

# 1. Build production assets
npm run build

# 2. Switch to dist branch (or create it)
git checkout dist

# 3. Copy dist/ contents to root and commit
cp -r dist/* .
git add .
git commit -m "Deploy v32"
git push origin dist

# 4. Switch back to main
git checkout main

In your GitHub repository settings:

• Settings → Pages → Source: Deploy from branch
• Branch: dist / / (root)

---

📁 Project Structure

saturamadhan/
├── 🌐 index.html               # Main HTML entry point
├── ⚙️ sw.js                     # Service Worker (offline caching)
├── 📋 manifest.json             # PWA manifest
├── 📦 package.json              # Build dependencies
│
├── 🎨 assets/
│   ├── css/
│   │   ├── style.css            # CSS entry (imports all components)
│   │   ├── base/                # Variables, fonts, reset, typography
│   │   ├── layout/              # Container layout
│   │   └── components/          # 15 modular component stylesheets
│   ├── js/
│   │   ├── loader.js            # Module loader with splash screen
│   │   ├── app.js               # App coordinator & lifecycle
│   │   ├── main.js              # UI controller & event handling
│   │   └── modules/             # 8 feature modules (config, api,
│   │                            #   database, location, prayer,
│   │                            #   storage, ui, qibla)
│   ├── favicon/                 # App icon (WebP)
│   ├── font/                    # Poppins & Amiri typefaces
│   ├── icon/                    # Prayer time SVG icons + Kaaba
│   └── vendor/                  # Boxicons library
│
├── 🗄️ database/
│   ├── ramadhan.json            # ⭐ Ramadhan dates (update yearly!)
│   ├── province.json            # 34 Indonesian provinces
│   └── regency.json             # 500+ regencies with coordinates
│
├── 🔧 scripts/
│   └── build.js                 # Production build script (esbuild)
│
└── 📤 dist/                     # Production output (generated)

---

🔧 Configuration

🌙 Ramadhan Dates — database/ramadhan.json

Important

This file must be updated every year before Ramadhan begins.

{
    "tahunHijriah": 1447,
    "tahunMasehi": 2026,
    "tanggalSatuRamadhan": {
        "muhammadiyah": "2026-02-18",
        "nu": "2026-02-19"
    }
}

Field	Description
tahunHijriah	Hijri year of the upcoming Ramadhan
tahunMasehi	Corresponding Gregorian year
tanggalSatuRamadhan.muhammadiyah	1st Ramadhan date per Muhammadiyah (Hisab)
tanggalSatuRamadhan.nu	1st Ramadhan date per NU / Government decision

Dates must use YYYY-MM-DD format. After updating, rebuild and redeploy.

---

🔄 Cache Versioning

Caution

Since this is a PWA, the browser aggressively caches all assets via the Service Worker. You must bump the cache version on every deployment, or users will see stale content.

Steps to Update

1. Increment version in sw.js:

   - const CACHE_VERSION = 'v32';
   + const CACHE_VERSION = 'v33';

2. Match version in scripts/build.js:

   - "const CACHE_VERSION = 'v32-dist'"
   + "const CACHE_VERSION = 'v33-dist'"

3. Rebuild and deploy:

   npm run build

Caching Strategies

Strategy	Assets	Behavior
Cache-first	CSS, fonts, images, icons	Instant load from cache
Network-first	JS, HTML	Latest code from server, cache fallback
Stale-while-revalidate	API responses	Instant cached data + background refresh

---

🛠️ Tech Stack

• No frameworks — Pure vanilla HTML, CSS, and JavaScript
• No server runtime — Fully static, hosted on GitHub Pages
• Modular CSS — 19 component files with CSS Custom Properties design system
• Modular JS — 10 self-contained modules loaded in sequence
• Build tool — esbuild for blazing-fast minification

---

🤲 API

Prayer times are fetched from the Aladhan Prayer Times API:

• Calculation Method: Kemenag RI (Method 20)
• Coordinates: User's GPS or manually selected regency
• Fallback: Multiple API mirrors for high availability
• Caching: GPS coordinates normalized to 4 decimal places (~11m) for optimal cache hit rate

---

📜 Copyright

© 2026 Satu Ramadhan — All rights reserved.

This project is proprietary software. Unauthorized copying, modification, distribution, or use of this software, via any medium, is strictly prohibited without explicit written permission from the author.

---

_{Built with ❤️ for the Muslim community — Ramadhan Kareem!}