nyx app

The Nyx astronomy REST + WebSocket backend (apps/nyx/api). src/app.ts builds an OpenAPIHono app with secure-headers/CORS/rate-limit/api-key middleware and mounts four routers — objects, ephemeris, events, satellites — under /api/v1, serving Swagger UI at /api/docs from the canonical libs/openapi/docs/nyx/openapi.yaml. src/index.ts wires the HTTP server to a WebSocket layer (setupNyxWebSocket) with tier-prefixed API-key validation (nyx_pro_/nyx_ent_/nyx_) and channel subscriptions for object/satellite positions and event alerts. The services are real: services/ephemeris-service.ts delegates to the @nyx/ephemeris engine for solar-system targets, and services/objects-service.ts reads the bundled @nyx/messier catalog. Ships a Dockerfile; backend application, not a library.

A WebXR / camera augmented-reality sky map (apps/nyx/ar-sky), Vite + React. It fuses device sensors (src/ar/orientation.ts, camera.ts, session.ts) to project celestial coordinates onto a live camera feed, with an ARSkyScene, overlay renderers, and a tap-to-identify pipeline. The comprehensive type model in src/types/index.ts defines equatorial/horizontal/screen coordinate frames, star/planet/constellation/deep-sky data shapes, an OverlayLayerConfig, and helpers like magnitudeToSize/SPECTRAL_COLORS. src/identification/identifier.ts implements a real CelestialObjectIdentifier that matches taps/screen points to objects by angular distance with confidence scoring. Includes an assistant/ module (pointer, highlights, telescope control). Implemented app.

An astrophotography-planning tool library (apps/nyx/tools/astrophotography). calculator.ts (~780 lines) computes imaging windows, exposure/SNR, FOV and sampling, and tracking limits (the 500 rule, NPF rule, polar drift), against constants like the BORTLE_SCALE light- pollution table and DSO_TYPES. Companion targets.ts ranks deep-sky targets; all surfaced through Zod-validated config schemas in src/index.ts. Tested (*.spec.ts per module). Implemented tool.

One of five education courses (apps/nyx/education/courses/cosmology). It imports Lesson/Course from @nyx/lesson-framework and assembles six ordered lessons (Big Bang, cosmic expansion, dark matter, dark energy, the CMB, the fate of the universe) into an advanced-difficulty cosmologyCourse with learning objectives and a galactic-astronomy prerequisite. Each lesson is a real authored content module (e.g. lessons/01-big-bang.ts is ~600 lines). Content library composing the shared lesson framework.

An interactive demo library for the cosmic distance ladder (apps/nyx/education/demos/distance-ladder). It provides the data, calculations, and state for visualizing each "rung": parallax.ts (parallaxToDistance), cepheids.ts (period-luminosity / calculateCepheidDistance), supernovae.ts (Type Ia standard candles), and hubble-law.ts (redshift-distance), with a state.ts reducer (createInitialState/selectRung) and typed rungs. Real astronomy math with a documented example in the barrel. Implemented demo.

The introductory education course (apps/nyx/education/courses/fundamentals). Composes five lessons via @nyx/lesson-framework — celestial sphere, coordinate systems, magnitude/brightness, spectral types, electromagnetic spectrum — into a beginner fundamentalsCourse with no prerequisites. It is the root of the course dependency chain (solar-system → stellar → galactic → cosmology all list earlier courses as prerequisites). Implemented content library.

The galactic-astronomy course (apps/nyx/education/courses/galactic). Five authored lessons (Milky Way, galaxy types, galaxy evolution, active galactic nuclei, galaxy clusters) assembled into an advanced galacticCourse whose prerequisite is stellar-astronomy. Same @nyx/lesson-framework-composing shape as the other courses; real lesson content, not placeholders.

A demo library for gravity wells and orbital/black-hole physics (apps/nyx/education/demos/gravity-well). Modules cover the rubber-sheet gravity visualization (gravity.ts), Kepler-law orbits (orbital.ts), escape velocity (escape-velocity.ts), and black-hole physics — Schwarzschild radius, Hawking radiation (black-holes.ts) — plus physical constants and an interactive state.ts. Fully typed via types.ts/Zod schemas in the barrel. Implemented demo, real formulas.

An interactive Hertzsprung-Russell diagram demo (apps/nyx/education/demos/hr-diagram). Provides real stellar star-data.ts, diagram logic (hr-diagram.ts: temperature↔color, luminosity positioning, positionAllStars), regions.ts (main sequence, giants, etc.), stellar evolution-paths.ts tracks, and an animation-capable state.ts (selectStar/selectTrack/startAnimation). Implemented demo with a worked example in src/index.ts.

A variable-star light-curve analysis tool (apps/nyx/tools/light-curves, ~1,300 lines in src/index.ts). It implements genuine time-series astronomy: lombScargle periodogram, pdm (phase-dispersion minimization), stringLength, refinePeriod, phase folding/binning, Fourier fitting (fitFourier/ evaluateFourier), Nyquist-frequency estimation, AAVSO format parsing (parseAAVSOExtended/parseAAVSOVisual/toAAVSOFormat), robust statistics and outlier removal, and JD↔date conversion anchored on J2000_JD = 2451545.0. Implemented analysis library, domain-real algorithms.

A demo library for light-travel-time and lookback-time concepts (apps/nyx/education/demos/light-speed). It models Earth-Moon (~1.28 s), Sun-Earth (~8.3 min), and light-year journeys (light-travel.ts), the "seeing the past" lookback-time idea (lookback-time.ts), scripted scenarios.ts, speed comparisons, and interactive state.ts, on top of constants.ts and a typed surface. Implemented demo.

A Progressive Web App star map (apps/nyx/mobile), Vite + React — not a native app, as its own NATIVE_SCAFFOLDING.md states (the directory name is historical; there is no ios//android/). It renders a star-map canvas driven by device sensors (hooks/useSensors.ts, star-map/sensors.ts), supports offline storage/sync (offline/) and local notifications, and ships home-screen widgets (widget/components/: moon phase, ISS pass, planets-tonight, event alerts) plus Playwright e2e tests. Consumes the shared @nyx/* ephemeris/orbital libraries. Implemented PWA, honestly documented.

An observation-planning tool library (apps/nyx/tools/observation-planner). observation-planner.ts (~1,400 lines) computes visibility windows under altitude constraints, moon interference, and civil/nautical/astronomical twilight, with a WeatherProvider integration interface and export to AstroPlanner/CSV. It exposes real positional-astronomy utilities — Julian date, GMST/LST (calculateGMST/calculateLST), hour angle — alongside finder-chart and FOV helpers (finder-charts.ts, fov.ts). Tested per module. Implemented tool.

An Initial Orbit Determination tool (apps/nyx/tools/orbit-determination, ~2,400 lines). It implements classical and modern IOD end-to-end: a gaussMethod (documented as supporting Laplace, Herrick-Gibbs, double-r, differential correction, and Gooding), a full linear-algebra kernel (vector ops, matrix multiply/transpose, Gaussian-elimination solve, Gauss-Jordan inverse), Kepler solvers (elliptic and hyperbolic), anomaly conversions, and stateToElements/elementsToState, with constants like MU_SUN/MU_EARTH/ AU_KM to CODATA precision. Implemented tool, real orbital mechanics.

An education challenge library (apps/nyx/education/challenges/orbital-mechanics) for orbital-mechanics problems. It is real physics, not CRUD: escape-velocity.ts computes √(2μ/r), circular velocity, and Hohmann-transfer parameters; conjunction-prediction.ts computes synodic periods and time-to-conjunction/ opposition; plus anomaly-conversion.ts and orbit-classification.ts. The src/index.ts barrel exports an extensive set of Zod schemas (orbital elements, state vectors, transfers, question/answer/session types) and a challenge-service.ts that generates and scores questions. type:education library tagged scope:challenges.

The Nyx headless data-pipeline workers (apps/nyx/pipelines), an esbuild-bundled Node application with four entry points: tle-updater.ts (satellite TLE refresh), catalog-syncer.ts, ephemeris-generator.ts, and event-calculator.ts (which has a .spec.ts). src/index.ts runs a daemon mode that starts a common/health-server.ts for K8s readiness/liveness probes, registers checks, and handles graceful SIGTERM/SIGINT shutdown; shared common/logger.ts/metrics.ts support the workers. Has a docker-build target. Implemented worker set.

The solar-system course (apps/nyx/education/courses/solar-system). Five lessons (formation, the Sun, terrestrial planets, gas giants, dwarf planets/small bodies) form an intermediate solarSystemCourse prerequisite-gated on astronomy-fundamentals. Built on @nyx/lesson-framework. Implemented content library.

A spectroscopy demonstration library (apps/nyx/education/demos/spectroscopy). blackbody.ts (~800 lines) implements real radiation physics — Planck's law B_λ(T) = (2hc²/λ⁵)·1/(e^(hc/λkT)−1), Wien's displacement, Stefan-Boltzmann — using exact CODATA constants (PLANCK_CONSTANT = 6.62607015e-34, etc.). Companion modules handle spectral lines, element identification, Doppler shift (doppler.ts), and spectral classification, with a typed state.ts. Implemented demo, domain-correct constants.

A star/constellation identification challenge engine (apps/nyx/education/challenges/star-identification). challenge-service.ts provides a ChallengeService (with an InMemoryStorageAdapter) that generates constellation-naming, star-identification, coordinate-pointing, and constellation-tracing questions, scores them, awards achievements (e.g. perfect-score), and supports timed modes and leaderboards. Backed by real data modules (stars.ts, constellations.ts, coordinate-pointing.ts, timed-challenges.ts) and a full type surface in types.ts. Implemented library, not a scaffold.

The flagship 3D star-map web app (apps/nyx/star-map), Vite + React + Three.js and by far the largest project in the area (~180 source files, almost all with co-located .spec.ts tests, plus a Dockerfile/nginx.conf for deployment). It is organized into deep feature modules: modes/ (orrery with Lagrange points and asteroid belt, eclipse, navigation/voyages, cosmic-zoom, overview-effect, pale-blue-dot, synchronicity, transits/ISS), overlays/ (constellations, grids, orbits, sacred-geometry), satellites/ (ISS/Starlink trackers), time-travel/ (precession, stellar evolution, supernova), plus search, bookmarks, collections, journaling, mythology tours, solar-weather, NEO impact, meditation/audio, and observation planning. Implemented flagship application.

The stellar-astronomy course (apps/nyx/education/courses/stellar). Six lessons (star formation, main sequence, stellar evolution, variable stars, binary stars, stellar death) assembled into an intermediate stellarCourse requiring solar-system. Same framework-composing pattern; real authored lessons.

A WebXR VR planetarium dome (apps/nyx/vr-planetarium), Vite + React + Three.js. xr/session-manager.ts/controller-manager.ts manage the WebXR session; dome/star-dome.ts builds the procedural star dome (equatorial↔Cartesian projection, magnitude-to-size/brightness, custom shader material) with milky-way.ts and constellations.ts layers; interaction/ adds a gaze cursor and info panels; navigation/ handles teleport/scale; tours/ drives guided tours. Notably dome/v1-nyx-sky.ts renders a live, staleness-bounded sky dome for the fixed "Lilith Commons Observatory" site by driving the @nyx/ephemeris engine — the V1/nisaba live-sky feature. Implemented WebXR application.