A web‑based stargazing application with a FastAPI backend and a React/Vite frontend. The backend computes real‑time astronomical data (stars, planets, deep sky objects, constellations, Moon phases, etc.) using Jean Meeus's algorithms, and the frontend renders an interactive sky map you can explore from any latitude/longitude and time.

• Accurate positions for 1 000+ stars, planets, Sun, Moon, deep‑sky objects
• Constellation outlines and selectable subsets
• Full‑sky & viewport modes with click‑to‑inspect details
• Time offset slider for future/past sky simulation
• Mobile‑friendly UI with adjustable display settings
• Country capital lookup for quick location selection
• Lightweight 2‑dependency backend and a minimal modern React frontend

frontend/         ← React/Vite UI (App.jsx, components/)
backend/          ← Python FastAPI service (astronomy.py + main.py)
Dockerfiles       ← build images for each tier

The frontend calls /api/sky with lat, lon, and optional Julian day to obtain a JSON payload with computed objects and screen positions. Additional endpoints provide capital coordinates and a health check.

All astronomical math lives in backend/astronomy.py; the public interface is get_sky_data() which the FastAPI routes use.

You can run the project locally or build Docker images for deployment.

• Python 3.11 (or 3.10+) with venv support
• Node 18+ / npm or yarn
• Git (for cloning)
• Optional: Docker & Docker Compose for containerized setup

cd backend
ing python -m venv .venv           # create virtual env
.\.venv\Scripts\activate        # Windows (use source on mac/linux)
pip install -r requirements.txt
uvicorn main:app --reload --port 8000

The service listens on http://localhost:8000. Open http://localhost:8000/docs to see the autogenerated OpenAPI swagger UI.

cd frontend
npm install        # or yarn
npm run dev        # starts Vite on http://localhost:5173

By default the client is configured to fetch from http://localhost:8000. Modify the BASE_URL constant in src/hooks/useSkyData.js if you need a different address.

Start backend then frontend and open the web UI in a browser. You can also run both with Docker Compose (see below).

/api/sky returns a JSON object containing arrays of stars, planets, constellations, deep_sky objects and metadata such as the Julian day, LST, etc. Consult backend/astronomy.py for the exact schema.

Key components live under frontend/src/components:

• SkyCanvas.jsx – renders canvas with objects and handles clicks
• LocationModal.jsx – lets user pick latitude/longitude or country
• Toolbar.jsx, InfoPanel.jsx, ConstellationPanel.jsx – UI controls
• DetailDrawer.jsx – slide‑out sheet with information about selected object
• StarField.jsx – animated background stars when no location is set

Custom hook useSkyData encapsulates fetching logic and loading/error state.

Styling is done inline for simplicity but CSS variables defined in index.css control colors, fonts, etc.

A root-level Dockerfile is provided for monorepo deployments (e.g. Render.com). It builds the frontend, copies the static assets into the backend and serves everything from a single FastAPI process.

Each tier also has its own Dockerfile if you prefer separate containers; you can build them manually or use Compose:

# docker-compose.yml
version: '3.8'
services:
  backend:
    build: ./backend
    ports:
      - "8000:8000"
  frontend:
    build: ./frontend
    ports:
      - "5173:80"   # nginx serves the build on port 80
    depends_on:
      - backend

When using the root Dockerfile directly you can specify a listening port via the PORT environment variable (Render sets this automatically and commonly uses 10000):

# local test, default port is 8000
docker build -t celestia-all .
docker run -e PORT=8000 -p 8000:8000 celestia-all

The container command honors ${PORT:-8000} so it will bind correctly on Render without further changes.

docker-compose up --build

The frontend expects the backend at http://backend:8000 when running in Compose; you can override with an env var if needed.

• Add new objects or improve the astronomy engine in backend/astronomy.py (well‑commented and based on Meeus algorithms).
• UI changes go in frontend/src; the project uses plain React without a state library.
• eslint/formatter not included but you can add them if desired; the code is intentionally minimal.

The backend has no automated tests yet; consider adding pytest and verifying the core functions like julian_day and planet_radec.

1. Fork the repo and create a feature branch.
2. Write tests for your changes where applicable.
3. Open a pull request with a clear description of what the change accomplishes.

Please keep the dependency list lean and prefer pure‑Python math for the backend.

This project has no license file; add one (MIT, Apache‑2.0, etc.) as appropriate before sharing publicly.

Happy stargazing! ✨