Your night sky, computed on your own machine — no cloud, no keys, no tracking.
سماؤك الليلية، محسوبة على جهازك أنت.
Falak ("orbit / celestial sphere" in Arabic) is a small, self-hostable astronomy companion that answers one question beautifully: "what is in my sky right now, and what is worth looking at tonight?" — for any city on Earth.
It is a single Python web app with exactly one dependency
(ephem). Everything — sun, moon, planets,
twilight, ISS passes, prayer times, qibla, crescent visibility, tides, a live
star map and an animated solar-system orrery — is computed locally from orbital
mechanics, served from the Python standard library, and rendered by a
self-contained frontend with fonts bundled on disk.
- Offline-first, for real. Pull the network cable and Falak keeps working. No CDN fonts, no external JavaScript, no cloud SDKs. The one thing that genuinely cannot be computed offline (the ISS's current orbit) is cached and degrades honestly — see Data honesty.
- Private by construction. No API keys, no accounts, no analytics, no telemetry. Your location never leaves your machine, because there is nothing for it to leave to.
- Arabic-first, world-ready. Prayer times, qibla, Hijri date and new-crescent visibility are first-class features computed from first principles — and the whole UI ships in 8 languages with full RTL layouts.
- Honest about its data. Where a number would require a service or a survey Falak doesn't have, it says so instead of pretending (tides are labeled as astronomical estimates, stale TLE reports its age).
| Feature | What you get | |
|---|---|---|
| ☀️ | Sun & twilight | Altitude/azimuth now, rise/set, solar noon, day length, and the full twilight ladder (civil / nautical / astronomical, dawn & dusk). |
| 🌙 | Moon | Phase name, illuminated %, age in days, rise/set, next full & new moon — with an accurate SVG drawing of the currently lit fraction. |
| 🪐 | Planets | Mercury, Venus, Mars, Jupiter, Saturn: position, magnitude, up/down, rise/set, viewing notes, and close conjunctions. |
| 🛰️ | ISS passes | Visible pass predictions for the next 48 h from real orbital elements (TLE), cached from CelesTrak so predictions keep working offline. |
| 🗺️ | Live star map | A self-contained SVG chart of the sky above you right now — zenith at the center, horizon at the rim, stars, planets, sun and moon in their true positions. Dark-sky-friendly palette, zero libraries. |
| 🌌 | Solar-system orrery | An animated top-down view of the planets in their orbits, from real heliocentric longitudes. |
| ✨ | Stars, constellations & meteors | Constellations currently up, the brightest stars (with their traditional Arabic names), and the annual meteor showers with peak dates, ZHR, and how badly the moon will interfere. |
| 🔭 | Deep-sky highlights | The classic naked-eye / binocular showpieces (Andromeda, Orion Nebula, the Pleiades, …) that are above your horizon right now. |
| 🌊 | Tides | Tide timing and relative range from lunar/solar geometry — clearly labeled an astronomical estimate, never fake surveyed heights. |
| 🌃 | Tonight | A ranked "what to look at" digest plus the best dark-sky window (astronomical dusk → dawn, minus the time the moon is up). |
What makes Falak distinctive — computed locally from first principles, not fetched from an API:
- Prayer times — Umm al-Qura method by default, derived directly from solar depression angles.
- Qibla bearing — great-circle math from your coordinates.
- New-crescent visibility — Odeh/Yallop criteria evaluated after your local sunset (altitude, elongation, lag).
- Hijri date — alongside the Gregorian one.
The entire interface — every label, phase name, prayer name, compass point and "tonight" reason — is translated into eight languages, with full right-to-left layouts for Arabic and Urdu:
العربية (RTL) · English · Français · Español · اردو (RTL) · हिन्दी · Türkçe · 中文
Switching language re-renders instantly from the last payload (no refetch) and
flips direction and fonts. Light & dark themes, mobile-first, one page.
Typography is the UAE Design System stack — Alexandria, Noto Kufi Arabic
and Inter — bundled locally as woff2, so the UI looks right with zero
internet.
Three layers deliver the offline promise:
- Local computation. All astronomy — rise/set, phases, twilight, prayer times, qibla, crescent, conjunctions, orrery positions, tide timing — is PyEphem math executed on your machine. Answering a request fetches nothing.
- Bundled catalogs ship in the repo (
data/): 366 seed cities, bright stars with traditional Arabic names, constellation names, and the annual meteor-shower calendar. - Cached TLE — the one network exception. Satellite orbits genuinely
change, so Falak fetches fresh elements from
CelesTrak when it can, caches them in
data/tle_cache.json, and reuses the cache offline. The response always discloses the elements' age (tle_age_hours) and origin (network/cache/none) — and with no cache at all, the ISS card says so instead of guessing.
The same honesty applies to tides: Falak computes timing and relative range
(spring/neap, perigee) from geometry alone and labels itself
"type": "astronomical_estimate" — real water heights would require local
harmonic constants or a keyed API, so it never pretends to know them.
git clone <your-fork-or-clone-url> falak && cd falak
pip install -r requirements.txt # installs exactly one package: ephem
python3 backend/server.pyOpen http://localhost:8091. The page asks for your location (browser geolocation → city picker → Dubai fallback) and renders your sky.
That's the whole deployment — no build step, no database, no environment
variables. The server binds to 127.0.0.1:8091; to share it with other devices
on your LAN or add TLS, put an nginx reverse proxy (or any reverse proxy)
in front of port 8091. Entirely optional.
Run the test suite (fully offline — the network is stubbed):
python3 tests/test_smoke.pybrowser (frontend/index.html + i18n.js + skymap.js)
│ GET /api/sky?lat=&lon=&tz=&elev=
▼
backend/server.py (stdlib http.server, 127.0.0.1:8091)
│ fresh observer clone per module · try/except per slot
▼
sun · moon · planets · satellites · stars_meteors · arabic · tides · solarsystem · tonight
│ PyEphem math + bundled catalogs in data/
▼
{"sun": {...}, "moon": {...}, ..., "tonight": {...}} ← always HTTP 200
The design rests on three deliberate contracts (full detail in docs/ARCHITECTURE.md):
ephem-only module contract. Every backend module exposes exactly one entry point,compute(obs, when_utc) -> dict— a plain JSON-serializable dict, angles in degrees, times as ISO 8601 UTC. No numpy, no flask, no requests; the web server is the Python standard library.- Per-slot error isolation.
server.pywraps each module call in its owntry/exceptand hands each a fresh observer clone. A corrupt TLE cache or a polar edge case poisons its own card only — the response stays HTTP 200 and the rest of the sky still renders. One broken instrument never blanks the page. - i18n by token maps, not backend prose. The backend is language-blind: it
emits snake_case tokens and structured reason dicts
(
{"code": "moonlit_all_night", "illum": 96}), andfrontend/i18n.jsmaps them into the active language. Adding a language means adding one complete block to one file.
| Language | Code | Direction |
|---|---|---|
| العربية (Arabic) | ar |
RTL |
| English | en |
LTR |
| Français | fr |
LTR |
| Español | es |
LTR |
| اردو (Urdu) | ur |
RTL |
| हिन्दी (Hindi) | hi |
LTR |
| Türkçe | tr |
LTR |
| 中文 (Chinese) | zh |
LTR |
Want yours added? It's a single self-contained block in frontend/i18n.js —
see CONTRIBUTING.md.
- Live sky-map refinements — constellation stick figures, a pointing mode that follows device orientation on mobile.
- Comets — bright-comet elements with the same cache-and-degrade honesty as the TLE pipeline.
- More satellites — Tiangong and bright Starlink trains alongside the ISS.
- Optional observing weather — cloud cover / seeing forecast, clearly labeled as an online-only feature and off by default.
- More localization — additional languages, more seed cities, per-location favorites.
- Installable PWA — offline shell + home-screen icon.
Small, focused PRs are very welcome — translations especially. Falak is intentionally tiny; the ground rules (one dependency, offline-first, no build step) and step-by-step guides for adding a language or a data catalog are in CONTRIBUTING.md. Bug reports have a ready-made template.
MIT — do what you like, keep the notice.
فلك رفيقك الفلكي الصغير المستضاف ذاتياً: يجيب عن سؤال واحد بشكل جميل — «ماذا في سمائي الآن، وما الذي يستحق النظر الليلة؟» — لأي مدينة في العالم. الشمس والشفق، والقمر برسم SVG دقيق لطوره، والكواكب الخمسة المرئية بالعين، ومرورات محطة الفضاء الدولية، وخريطة سماء حيّة، ومجسّم متحرك للمنظومة الشمسية، وزخّات الشهب والنجوم الساطعة والكوكبات، وأبرز أجرام السماء العميقة، والمدّ والجزر (تقدير فلكي صريح) — إضافة إلى الطبقة العربية: مواقيت الصلاة (أم القرى)، واتجاه القبلة، ورؤية الهلال (معياري عودة/يالوب)، والتاريخ الهجري.
الفلسفة: يعمل دون إنترنت، بلا مفاتيح API، بلا حسابات، بلا تتبّع. الخلفية
كلها بايثون ٣ + مكتبة ephem فقط، وكل الحسابات تجري محلياً على جهازك من
ميكانيكا المدارات؛ لا يغادر جهازَك أيُّ شيء عن موقعك أبداً. الاستثناء الوحيد
هو العناصر المدارية للمحطة الفضائية (TLE): تُجلب من CelesTrak عند توفر
الإنترنت وتُخزَّن في data/tle_cache.json فيواصل فلك العمل بها دون اتصال،
والاستجابة تصرّح دائماً بعمر العناصر ومصدرها. الواجهة بثماني لغات (العربية
والأردية من اليمين لليسار) وخطوط نظام التصميم الإماراتي مرفقة محلياً.
التشغيل:
pip install -r requirements.txt # فقط: ephem
python3 backend/server.pyثم افتح http://localhost:8091 في المتصفح — هذا كل شيء. ولتقديمه لأجهزة شبكتك المحلية أو خلف TLS يكفي وكيل nginx عكسي أمام المنفذ 8091 (اختياري تماماً). المساهمات — والترجمات خصوصاً — أهلاً بها: راجع CONTRIBUTING.md.