# Nyx — Systems Deep Dive

> 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.