Aaj: Offline Indian Daily Almanac & AGPL License Isolation Pipeline
Building an offline-first astronomical almanac PWA with Astro, build-time Swiss Ephemeris calculations, and an automated CI quarantine gate isolating AGPL-3.0 code from client bundles.
Aaj•Local-First & Distributed
Executive Architecture Summary
Aaj is a high-precision, offline-first consumer daily almanac (Panchang) progressive web app. Its core technical innovation lies in solving a difficult dual challenge: computing complex planetary astronomical ephemeris equations without loading heavy C libraries on mobile browsers, while strictly isolating AGPL-3.0 licensed calculation engines to protect proprietary application code.
The Problem Space & Inherent Failure Modes
Computing Vedic tithis, planetary coordinates, and solar ephemeris requires the Swiss Ephemeris library—a battle-tested C engine distributed under the strict AGPL-3.0 copyleft license. Bundling WebAssembly ports into client browsers not only bloats web apps by 10MB, but legally triggers AGPL distribution provisions, forcing the entire commercial codebase into open-source disclosure.
AGPL Build-Time Quarantine & Static Artifact Pipeline
Hermetic separation of AGPL build-time computation tools from client distribution assets.
UI updates instantaneously before network handoff
Core Invariants & Non-Negotiable Guarantees
No AGPL-3.0 code, C binary, or WebAssembly module is ever packaged into the client web distribution. Verified on every git commit via an automated CI quarantine scanner.
Precomputed sunrise, sunset, and tithi timestamps must match official Rashtriya Panchang ephemeris tables within a strict 60-second delta across all ~30 coordinate matrices.
Subsystems Architecture & Implementation Decisions
1. Build-Time Python Precomputation Engine
Architected an automated build-time pipeline using Python SwissEph that calculates high-precision celestial coordinates, lunar phases, and auspicious time intervals for ~30 major Indian urban centers across 2026-2028.
Key Architectural Decisions:
- •Precomputed data is structured into compressed, city-partitioned JSON tables for minimal bandwidth consumption.
- •Employed multiprocessing to reduce 3-year ephemeris calculations from 42 minutes to 85 seconds.
2. Automated CI Legal Quarantine Gate
Implemented a strict GitHub Actions compliance gate that scans compiled output bundles for banned license headers, symbol tables, and binary signatures before deployment approval.
Key Architectural Decisions:
- •Ensured unambiguous compliance with open-source software license governance.
- •Segregated calculation scripts into an isolated tools/ directory with explicit build-only execution flags.
3. Ultra-Lightweight Astro PWA with Service Worker Offline Storage
Engineered the frontend in Astro for zero unnecessary JavaScript hydration. When a user selects their city, the service worker downloads that city’s year-round JSON table (under 80KB), enabling instantaneous offline access in rural areas.
Key Architectural Decisions:
- •Eliminated all external font and analytics dependencies for maximum privacy and performance.
- •Designed responsive celestial time dials that compute user daylight progression locally using trigonometric math.
Failure Modes & Edge Case Recovery Protocols
Technologies & Engineering Standards
Verified Production Outcomes
- Precomputed over 32,000 individual astronomical daily facts with verified golden-set precision against Rashtriya Panchang standards.
- Achieved sub-50ms First Contentful Paint (FCP) on low-end Android mobile devices.
- Build-time calculation pipeline isolates Swiss Ephemeris AGPL dependencies from client bundle, ensuring clean IP ownership.
Interested in Similar Architectural Rigor?
Whether architecting distributed edge platforms, local-first data persistence, or high-correctness compliance software, discuss your system architecture directly with Harvinder Singh.