Eve library

Nyx — Systems Deep Dive

Guide

Revision 1

On this page

The apps/nyx/ area: the deliverable surface of the Nyx astronomy domain — one REST/WebSocket backend, four browser front-ends, a data-pipeline worker set, and a library of education modules and observer tools, all built on the shared @nyx/* astronomy engines.

What this area is#

Nyx is the Oshun platform's astronomy product. The apps/nyx/ tree holds its shippable applications and product-facing libraries — the things a user runs or a deployment serves — as opposed to the reusable astronomy engines (which live under libs/nyx/: @nyx/ephemeris, @nyx/messier, @nyx/lesson-framework, and friends). Every entity here either is a runnable app or is an application-scoped library that one of those apps composes.

The 22 tracked Nx projects split into five clusters. The API (@nyx/api) is the backend: a Hono server exposing /api/v1/objects|ephemeris|events|satellites plus a WebSocket channel layer, validated against the canonical libs/openapi/docs/nyx/openapi.yaml. The front-ends are four Vite/React apps — @nyx/star-map (the flagship 3D sky, ~180 source files of modes, overlays, and tools), @nyx/ar-sky (camera/WebXR augmented-reality sky), @nyx/vr-planetarium (WebXR dome), and @nyx/mobile (a PWA, despite the name — see its NATIVE_SCAFFOLDING.md). The pipelines (@nyx/pipelines) are headless data workers (TLE updates, catalog sync, ephemeris generation, event calculation). The education modules are seven libraries under education/ — five courses, two challenge engines — plus five interactive demos. The tools are four analysis libraries under tools/.

These projects relate through the shared engines rather than to each other directly: @nyx/api's ephemeris-service.ts calls @nyx/ephemeris, its objects-service.ts reads the @nyx/messier catalog, and the five courses all import the Lesson/Course types from @nyx/lesson-framework. The front-ends consume the API and the same engine libraries. So the area is wide but shallow in cross-dependency: a fan of consumers around a common astronomy core.

The branch theme (oshun-v1-nisaba, "V1") surfaces concretely in @nyx/vr-planetarium's src/dome/v1-nyx-sky.ts, which renders a live sky dome for a fixed "Lilith Commons Observatory" site by driving @nyx/ephemeris and bounding staleness with V1_NYX_SKY_DOME_MAX_LAG_MS.

How it fits the wider system#

The API is the integration boundary: deployments serve it (it ships a Dockerfile, as does star-map), and its OpenAPI document is the same spec the libs/openapi tooling owns, so external clients and the BFF see one contract. The front-ends are static bundles (@nx/vite:build) that hit that API and run the astronomy engines client-side for interactivity. The pipelines feed the data layer the API and apps read from. The education and tool libraries are type:library building blocks — they expose pure, well-typed functions (period analysis, orbit determination, lesson content, challenge generation) that the UI apps and other Nyx surfaces import. Walk the "used by" edges on any node below to see exactly who composes it; the consistent boundary is that everything depends down into libs/nyx/* engines, never sideways between apps.

Entity reference#

@nyx/api#

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.

@nyx/ar-sky#

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.

@nyx/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.

@nyx/star-identification#

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.

@nyx/cosmology-course#

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.

@nyx/fundamentals-course#

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.

@nyx/galactic-course#

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.

@nyx/solar-system-course#

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.

@nyx/stellar-course#

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.

@nyx/distance-ladder#

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.

@nyx/gravity-well#

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.

@nyx/hr-diagram#

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.

@nyx/light-speed#

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.

@nyx/spectroscopy#

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.

@nyx/mobile#

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.

@nyx/pipelines#

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.

@nyx/star-map#

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.

@nyx/astrophotography#

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.

@nyx/light-curves#

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.

@nyx/observation-planner#

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.

@nyx/orbit-determination#

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.

@nyx/vr-planetarium#

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.