Explore astronomical objects and scale through interactive 3D, 2D, and comparison views.
Website · Live demo · Documentation
AstroGuide turns abstract astronomical objects and orders of magnitude into something people can explore. Its catalog of 39 celestial objects is available through a navigable 3D scene, an interactive 2D map, and a visual size comparison.
The application is static, English-first with maintained French, Spanish, and German locales, account-free, and runs without a backend, analytics, cookies, or remote API calls.
The catalog, labels, and views below come from the isolated public demo. Screenshots use the English interface with the demo intro dialog closed.
| Interactive 2D map | Visual comparison |
|---|---|
| A zoomable, pannable overview of the same catalog for mouse and touch input. | Compare approximate diameters and extents while filtering the objects that matter. |
 |
 |
- Searchable catalog of stars, planets, galaxies, black holes, and larger systems.
- Interactive 3D view with textured bodies, animated orbits, camera controls, and fallback materials.
- Zoomable and pannable 2D map for mouse and touch input.
- Size-comparison view with filters and selectable objects.
- Responsive layouts for desktop, tablet, portrait mobile, and low-height landscape screens.
- WebGL rendering pauses when the 3D view is hidden.
- No account, backend, personal-data collection, or API key.
The tracked Compose file is intentionally small and pulls the published GHCR image:
services:
astroguide:
image: ghcr.io/lucas-lepajollec/astroguide:latest
ports:
- "2502:2502"
restart: unless-stoppedgit clone https://github.com/lucas-lepajollec/AstroGuide.git
cd AstroGuide
docker compose pull
docker compose up -d
docker compose psOpen http://<server-ip>:2502 from your LAN, or http://localhost:2502 on the Docker host.
AstroGuide uses port 2502 both on the Docker host and inside the container, so the mapping stays easy to recognize. To build the current checkout instead, run docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build.
For a controlled update, record the current image digest with docker image inspect, pull, recreate, and verify the health status. To roll back, change the Compose image: line to a previous sha-<full-commit> or version tag and recreate the service. docker compose down removes the container and network; AstroGuide has no persistent server-side data.
Requirements: Node.js 22.12 or newer within the Node.js 22 line, and npm 10 or newer.
git clone https://github.com/lucas-lepajollec/AstroGuide.git
cd AstroGuide
npm ci --include=optional
npm run devOpen http://127.0.0.1:2499. Use npm run dev:lan only for deliberate testing on a trusted network.
AstroGuide has no server-side data, database, account, runtime secret, or required environment variable. The catalog, textures, and application are part of the static build. A page reload restores the initial interface state.
Catalog changes belong in src/data/ and must be reviewed like source code rather than edited as runtime configuration.
Important
AstroGuide is an educational visualization, not a precision astronomical simulator.
- Rendered positions, visual distances, orbits, and 3D sizes are illustrative.
- Text values are rounded; some astrophysical quantities remain uncertain.
- The comparison view applies a minimum visible size.
- Distant black-hole masses depend on models and estimates; Phoenix A is deliberately presented as a highly uncertain candidate.
- WebGL capability and device performance affect the 3D experience.
- No cookie, local storage, analytics, API key, or remote data service is used.
Current orders of magnitude draw primarily from NASA Solar System Exploration, the Event Horizon Telescope results for M87*, NASA material about Betelgeuse, and Hubble/Gaia work on the Milky Way–Andromeda future.
Contributions that change the catalog must cite a scientific or institutional source and preserve coherent units.
| Layer | Technology |
|---|---|
| Interface | React 19, TypeScript, Tailwind CSS 4, Motion |
| Visualization | Three.js, React Three Fiber, Drei |
| State | Zustand |
| Tooling | Vite 6, Vitest, ESLint |
| Deployment | Static build or unprivileged Nginx container |
src/components/ # 3D, 2D, comparison, and interface components
src/data/ # Celestial catalog and integrity tests
src/store/ # Zustand state and tests
public/textures/ # Bundled astronomical textures
npm run check| Command | Purpose |
|---|---|
npm run lint |
Run ESLint with zero warnings allowed. |
npm run typecheck |
Validate TypeScript without emitting files. |
npm run test |
Run the Vitest suite. |
npm run build |
Create the production build. |
npm run build:demo |
Build the isolated public-demo variant. |
The public demo is the real static product with explicit demo onboarding, permanent labeling, reset control, and noindex directives. It adds no backend, external account, or fictional scientific dataset. See DEMO.md.