Answers the question every amateur astronomer actually has:
Live demo · Features · Architecture · Getting started
 Dashboard Location, telescope, conditions and Astro, the AI assistant |
 Target panel Real imagery, a 0–100 score, and live visibility for your sky |
 Alignment The phone streams orientation; the app talks you onto target |
 Explore All 13,311 objects — charted, filtered, searchable |
 Gallery The ten most-loved nights, fanned out |
 Community Nearby observers on a privacy-safe map (~40 km cells) |
 1. Scan — the QR opens the installed companion |
 2. Follow — rotate and tilt until it reads 0° off target |
 3. Everything else — the full app is responsive too |
SkyGuide AI is not a catalog viewer. It ranks tonight's actual sky for your telescope, from your location, under your conditions — then walks you onto the target.
| Feature | What it means | |
|---|---|---|
| 🎯 | Personalized recommendations | Every object scored 0–100 for your aperture, field of view, light pollution, moon interference and observing history |
| 🌙 | Tonight's Brief | A short written observing plan for the night, generated from live sky state |
| 🔭 | Telescope alignment | Mount your phone on the scope; its orientation streams over WebSocket and the app guides you onto the target live |
| 🌌 | 13,311 deep-sky objects | Messier + NGC + IC, with imagery, science data, rise/transit/set and live geometry |
| 📍 | Sky quality mapping | Bortle-aware scoring plus suggested darker sites nearby |
| 🛰️ | Satellite & ISS passes | Visible, sunlit passes only — not just anything overhead |
| 📋 | Observation planner | Queue targets, mark them observed, build an observing résumé |
| 👥 | Community | Nearby observers on a privacy-safe map (~40 km cells, never exact coordinates), regional chat and DMs |
| 🖼️ | Community gallery | Share your night's photos, like others'; the ten most-loved are featured, each paired with a line from the astronomy canon |
| 🔔 | Alerts & digest | Nightly digest plus event alerts: great nights, ISS passes, season-ending targets, new-moon windows |
| 🤖 | Astro, the AI assistant | Answers astronomy and app questions, grounded in your live context |
A distributed three-service system. The split is deliberate: scientific computation never happens in JavaScript, and the browser never touches the engine.
┌────────────────────────┐
│ React 19 Frontend │
│ (Vite · Tailwind 4) │
└───────────┬────────────┘
│ REST + Socket.IO
│ (HTTP-only cookie auth)
┌───────────▼────────────┐
│ Express 5 Gateway │
│ auth · sockets · CRUD │
│ rate limits · cron │
└─────┬────────────┬─────┘
│ │
X-Internal-Key │ │
(server-to-server) │ │
┌─────▼──────┐ ┌──▼──────────┐
│ FastAPI │ │ MongoDB │
│Astro Engine│──│ Atlas │
│ Astropy │ └─────────────┘
│ Skyfield │
│ Astroplan │
└────────────┘
PRIVATE SERVICE
(never browser-facing)
| Service | Owns | Never does |
|---|---|---|
| Frontend (React 19, Vite, Tailwind 4) | UI, visualization, sensor capture, socket client | Astronomical calculation |
| Gateway (Express 5, Socket.IO, Mongoose) | Auth, sessions, profiles, rooms, pairing, CRUD, scheduling | Astronomy math |
| Astro Engine (FastAPI, Astropy, Skyfield, Astroplan) | Coordinates, visibility, planning, scoring, recommendations | Anything user-facing |
The engine is a private service. Browsers reach its public science endpoints only through the gateway's allowlisted proxy at /api/v1/astro/*; the engine itself requires a shared X-Internal-Key and refuses to start in production without one.
Frontend — React 19 · Vite · Tailwind CSS 4 · Framer Motion · GSAP + ScrollTrigger · Three.js · MapLibre GL · Recharts · TanStack Query · Socket.IO client
Gateway — Node.js · Express 5 · Socket.IO · Mongoose · JWT (HTTP-only cookies) · bcrypt · Helmet · express-rate-limit · node-cron · Nodemailer · Groq SDK
Astro Engine — Python 3.13 · FastAPI · Motor (async MongoDB) · Astropy 8 · Astroplan · Skyfield · Astroquery · NumPy
Data — MongoDB Atlas · OpenNGC catalog · Celestrak TLEs · OpenWeather · OpenStreetMap Nominatim
- Node.js 20+
- Python 3.11+
- MongoDB Atlas cluster (or local MongoDB)
- (optional) cloudflared — only for LAN/tunnel dev modes
git clone https://github.com/watermelon588/skyguide-ai.git
cd skyguide-ainpm install && npm --prefix frontend install && npm --prefix server-gateway installcd astro-engine && python -m venv venv && ./venv/Scripts/activate && pip install -r requirements.txtOn macOS/Linux use
source venv/bin/activateinstead.
Copy each template and fill it in:
cp server-gateway/.env.example server-gateway/.env
cp astro-engine/.env.example astro-engine/.env
cp frontend/.env.example frontend/.envGenerate the two shared secrets:
node -e "console.log('JWT_SECRET =', require('crypto').randomBytes(32).toString('hex')); console.log('INTERNAL_API_KEY=', require('crypto').randomBytes(32).toString('hex'))"
⚠️ INTERNAL_API_KEYmust be identical inserver-gateway/.envandastro-engine/.env— it is how the engine knows a request came from the gateway.
cd astro-engine && ./venv/Scripts/python.exe scripts/seed_ngc_catalog.pyOne command starts all three services:
npm run dev| Command | Mode |
|---|---|
npm run dev |
localhost only |
npm run dev:lan |
reachable from phones on your Wi-Fi |
npm run dev:tunnel |
public Cloudflare Quick Tunnels (needed for phone sensors — they require HTTPS) |
| Service | URL |
|---|---|
| Frontend | http://localhost:5173 |
| Gateway | http://localhost:5000 |
| Astro Engine | http://localhost:8000 ( /docs for Swagger ) |
📱 Phone sensors require HTTPS. Use
npm run dev:tunnelto test alignment on a real device.
- HTTP-only cookie sessions — JWTs are never exposed to JavaScript, never in
localStorage - bcrypt password hashing (cost 12)
- Engine isolation — shared-key auth, allowlisted proxy, API docs disabled in production
- Layered rate limiting — failed-login, OTP-guess, password-reset and LLM-spend limiters, each keyed appropriately
- Proxy-aware —
trust proxyfollows deployment shape, so limits can't be forged or collapse into one shared bucket - Privacy by design — community location is a ~40 km geohash cell centre; public profiles are built from an explicit whitelist, never a raw document
- Generic auth responses — login and password-reset reveal nothing about which accounts exist
skyguide-ai/
├── frontend/ React 19 SPA + mobile companion (/align.html)
│ └── src/
│ ├── components/ UI, grouped by feature
│ ├── context/ Auth, Socket, Pairing, Chat, Toast
│ ├── hooks/ Data-fetching + behaviour hooks
│ ├── pages/ Route components
│ └── services/ ALL API calls live here
├── server-gateway/ Express 5 gateway
│ └── src/
│ ├── controllers/ Thin HTTP shaping
│ ├── services/ Business logic
│ ├── models/ Mongoose schemas
│ ├── sockets/ Socket.IO namespaces
│ ├── jobs/ Cron (digest, alerts)
│ ├── middleware/ Auth, rate limiting
│ └── uploads/ Gallery photos (runtime data, gitignored)
└── astro-engine/ FastAPI scientific engine
└── app/
├── api/v1/ Routers
├── services/ Astronomy + ML
├── schemas/ Pydantic contracts
└── core/ Config, DB, logging
- ML transparency prediction model
- Airmass & altitude curve visualizations
- Native mobile companion (React Native)
- Multi-telescope profiles per observer
- Astrophotography session planner
- GoTo mount control integration
(Add a license — MIT is the common choice for portfolio projects.)
Built by Rohit Maity
Clear skies. 🔭