Nyx Domain — Features

Nyx is the Cosmic Observatory Platform of the Oshun monorepo. Named after the Greek primordial goddess of night — one of the first entities born from Chaos, mother of Hypnos (Sleep) and Thanatos (Death), dwelling at the edge of the cosmos where no god could follow — Nyx provides the complete technological stack for building astronomy applications, planetarium software, telescope control systems, astrophotography tools, and space education platforms. The domain spans an active package tree covering star catalogs (Hipparcos, Gaia DR3 with 1.8 billion sources, Tycho-2), multi-cultural constellation traditions (IAU, Chinese, Egyptian, Polynesian, Norse, and Indigenous American), orbital mechanics (JPL Horizons integration, high-precision ephemerides), real-time celestial calculations, deep-sky object databases spanning nebulae to gravitational wave events, exoplanet research and habitability analysis, solar system ephemerides, telescope hardware control (ASCOM, INDI), astrophotography automation, educational curricula, observation planning, historical sky simulation ("time travel"), real-time satellite tracking, and a comprehensive REST/WebSocket API with TypeScript and Python client libraries.

Nyx solves a concrete engineering problem: building astronomically accurate software is hard because the domain spans many specialised sub-fields — astrometry, orbital mechanics, photometry, time systems, hardware control — each with its own standards and vocabulary. Nyx packages each sub-field into a focused, well-typed library so that an application developer can write @nyx/ephemeris to compute a planet's position without needing to understand VSOP87 series arithmetic, or use @nyx/telescope to slew a mount without studying the INDI protocol specification.

The feature map below follows the layered structure of the domain: shared foundations first, then the data libraries (star catalogs, deep-sky catalogs, solar system), then computation (orbital mechanics, coordinate transforms, time), then rendering and visualisation, then real-time data, events, observation planning, user-facing tools, and finally the API and cross-domain integration.

Core Foundation Libraries#

Types (@nyx/types)#

The shared type system used across all Nyx libraries — 150+ TypeScript type definitions covering every astronomical domain. Rather than letting each library invent its own coordinate or magnitude types, @nyx/types defines them once so that the output of one library can flow directly into the input of another.

• Celestial Coordinate Types: Strongly typed representations for all major astronomical coordinate systems — Right Ascension/Declination (equatorial, J2000 epoch), Altitude/Azimuth (observer-relative horizontal), Galactic longitude/latitude (Milky Way plane-relative), Ecliptic coordinates (solar system plane-relative), and Supergalactic coordinates for large-scale structure. Each type carries its reference frame and epoch explicitly, preventing the class of bugs that arise from silently mixing coordinate systems.
• Celestial Object Types: Rich typed models for every category of astronomical object — stars (spectral type, luminosity class, parallax, proper motion), galaxies (Hubble morphological type, redshift, physical size), nebulae (nebula type, ionised vs molecular), clusters (open/globular, richness class, concentration), pulsars (period, period derivative, dispersion measure), black holes (mass, spin parameter, event horizon radius), and gravitational wave events (detector, chirp mass, merger type).
• Orbital Element Types: Typed representations of Keplerian orbital elements — semi-major axis, eccentricity, inclination, longitude of ascending node, argument of periapsis, mean anomaly at epoch — with conversions to state vectors (position + velocity).
• Observation and Planning Types: Session log entries, observation targets, equipment specifications (telescope aperture/focal length, eyepiece AFOV, camera sensor), site profiles (latitude, longitude, elevation, Bortle class), and imaging sequence parameters.

Constants (@nyx/constants)#

Precisely defined astronomical constants used across all Nyx calculations. Having a single authoritative source for constants avoids the subtle errors that arise when different libraries use slightly different values of, say, the speed of light.

• Physical Constants: Speed of light (299,792,458 m/s exact), gravitational constant G, Planck's constant, Boltzmann constant, Stefan-Boltzmann constant, electron charge and mass — all defined to IAU 2012 standard precision.
• Astronomical Unit Conversions: Parsec (3.0857×10¹⁶ m), light-year, astronomical unit (AU), arc-second to radian, degree-to-radian, and Julian day/year definitions. The parsec — the distance at which one AU subtends one arc-second of parallax — is the fundamental distance unit of stellar astronomy.
• Catalog Identifiers: Standard catalog designations (Messier, NGC, IC, HD, HIP, TYC, Gaia DR3) with format validators, ensuring catalog cross-references use correctly formatted identifiers.
• Spectral Classification: MKK spectral type and luminosity class tables, main-sequence star physical parameters by spectral type, and colour index calibrations for photometric conversions.

Utilities (@nyx/utils)#

Shared utility functions for coordinate maths, angle handling, and astronomical conversions. These functions appear in the hot path of many calculations, so they are collected here rather than duplicated across libraries.

• Angle Arithmetic: Correct wrap-around arithmetic for angles — adding two right ascension values near 0h/24h, computing angular separation using the Haversine formula, and normalising angles to canonical ranges without silent sign errors.
• Coordinate Transforms: Exact implementations of the spherical trigonometry transforms between all coordinate systems, incorporating precession (slow drift of Earth's rotation axis over 26,000 years), nutation (short-period wobble on the precessional cone), and aberration (apparent shift of star positions due to Earth's orbital velocity).
• Time Utilities: Julian Date calculation (the astronomer's universal time standard — continuous count of days since noon on January 1, 4713 BC), Modified Julian Date, conversion between UTC and Terrestrial Dynamical Time (TDT), and Delta-T tables for historical and future epochs. Delta-T is the difference between uniform TDT (used in solar system calculations) and irregular UTC (based on Earth's actual, slightly variable rotation).
• Magnitude Arithmetic: Logarithmic magnitude arithmetic (Pogson scale where each magnitude step is a factor of 100^(1/5) ≈ 2.512 in brightness), surface brightness from integrated magnitude and angular size, and limiting magnitude estimation for given aperture and sky conditions.

Star Catalogs#

Star catalog packages give applications access to the large reference datasets that professional astronomy depends on. Each catalog package encapsulates its data source, identifier syntax, and query interface behind a typed API so that callers never need to deal with raw TAP/ADQL or FITS files directly.

Hipparcos Catalog (@nyx/hipparcos)#

The ESA Hipparcos mission (1989–1993) produced the first high-precision space-based astrometric catalog — 118,218 stars with trigonometric parallaxes (and thus direct distance measurements) accurate to ~1 milli-arcsecond.

• Parallax-Based Distances: Every Hipparcos star has a measured trigonometric parallax — the apparent shift in a star's position as seen from opposite sides of Earth's orbit. Parallax in arcseconds inverted gives distance in parsecs. This is the geometric "gold standard" for distance measurement out to ~500 parsecs.
• Proper Motion Data: Annual angular velocity of each star across the sky (in RA and Dec), enabling position prediction at any epoch. Proper motion accumulates: Alpha Centauri moves ~4 arcseconds per year, meaning its position shifts by more than a full moon diameter per century.
• Photometric Data: Visual magnitude, B-V colour index, and spectral type for each star. B-V (difference between blue and visual band brightness) is a proxy for surface temperature: blue stars (B-V ≈ -0.3) are hot (>20,000 K); red stars (B-V ≈ +1.5) are cool (~3,500 K).
• Epoch J2000.0 Positions: All positions referenced to the J2000.0 epoch (January 1.5, 2000), the modern standard epoch for star coordinates, with formulae to propagate to any other epoch using proper motion.

Gaia DR3 Catalog (@nyx/gaia)#

ESA's Gaia mission has produced the most precise astrometric catalog in history — Gaia Data Release 3 (DR3, 2022) contains 1.8 billion objects with sub-microarcsecond parallaxes out to many kiloparsecs.

• 1.8 Billion Source Access: Query interface to the full Gaia DR3 catalog via TAP (Table Access Protocol) ADQL queries to the Gaia Archive. The catalog is too large to download in full — the library provides efficient on-demand access.
• Sub-Microarcsecond Astrometry: Gaia's parallax precision (~20 microarcseconds for bright stars) is 50× better than Hipparcos, extending reliable distance measurements to the far side of the Milky Way.
• Radial Velocity Spectroscopy: Gaia DR3 includes radial velocities (line-of-sight velocities from Doppler shifts) for ~33 million stars, enabling full 3D space motion (proper motion + radial velocity) for the largest stellar sample ever assembled.
• Photometric Classification: Gaia's BP/RP (Blue Photometer/Red Photometer) spectral energy distributions enable stellar classification, temperature estimation, and identification of chemically peculiar stars.

Tycho-2 Catalog (@nyx/tycho)#

The Tycho-2 catalog provides high-precision data for 2.5 million of the brightest stars derived from Hipparcos satellite measurements.

• TYC Identifier Handling: Parsing and formatting of Tycho-2 designations (TYC region-number-component, e.g., "TYC 1234-567-1") for cross-referencing with other catalogs.
• TAP/ADQL Query Interface: Access to the VizieR I/259 table for bulk and individual queries against the full catalog.
• BT/VT Photometry: Tycho's blue and visual magnitude measurements in the Tycho photometric system, with conversions to standard Johnson B and V magnitudes.

Yale Bright Star Catalog (@nyx/bright-stars)#

The Revised Yale Bright Star Catalog (BSC5) contains 9,096 stars brighter than magnitude 6.5 — essentially every star visible to the naked eye from a dark site.

• Complete Naked-Eye Star Database: Every star visible without optical aid, with full data including HR (Harvard Revised) numbers, HD (Henry Draper) catalog numbers, Flamsteed designations, Bayer Greek-letter designations, and common names.
• TAP/ADQL Client: Query interface for the VizieR V/50 table.
• Traditional Names: Association of popular star names (Sirius, Betelgeuse, Vega, Arcturus, Polaris) with their catalog counterparts, enabling human-friendly object identification.

SIMBAD Astronomical Database (@nyx/simbad)#

SIMBAD (Set of Identifications, Measurements, and Bibliography for Astronomical Data) at CDS Strasbourg is the authoritative reference for stellar and extragalactic objects — containing 15 million objects with cross-identification across hundreds of catalogs.

• Cross-Catalog Object Identification: Given any identifier (HD number, HIP number, NGC number, common name, Gaia source ID), SIMBAD resolves it to a canonical object with all other known identifiers, enabling seamless cross-referencing between catalogs.
• Object Type Hierarchy: SIMBAD's hierarchical object type taxonomy classifies objects at multiple granularities — "galaxy" → "spiral galaxy" → "barred spiral galaxy" → "starburst galaxy". Type-based queries retrieve all objects of a given class.
• TAP/ADQL and VOTABLE Queries: Full programmatic access to SIMBAD's query interface, returning results as TypeScript-typed data structures.
• Bibliography Cross-Reference: Each SIMBAD object links to its astronomical literature — papers that mention or study that specific object — useful for research applications.

Multi-Catalog Star Query (@nyx/star-query)#

A unified query interface that searches across Hipparcos, Gaia DR3, Tycho-2, and bright-stars simultaneously, resolving cross-identifications and deduplicating results.

Deep Sky Object Catalogs#

Deep-sky objects — galaxies, nebulae, clusters, and exotic compact objects — are spread across many specialist catalogs. Nyx packages each catalog separately and provides enough explanation about the object types that application developers can build informed UIs without needing an astrophysics background.

Messier Catalog (@nyx/messier)#

Charles Messier's 18th-century comet hunter's log inadvertently produced astronomy's most beloved catalog — 110 objects (M1–M110) covering the best nebulae, clusters, and galaxies visible from the Northern Hemisphere.

• 110 Objects with Full Metadata: Type (emission nebula, reflection nebula, planetary nebula, supernova remnant, open cluster, globular cluster, elliptical/spiral/irregular galaxy), size (major and minor axis in arc-minutes), visual magnitude, distance, and discovery history for all 110 objects.
• Observer Notes: Eyepiece appearance descriptions at various apertures — what to expect through 70mm binoculars vs a 200mm Dobsonian, helping observers calibrate expectations.
• Cultural Significance: Historical context for notable objects (M1 Crab Nebula — the 1054 AD supernova remnant; M31 Andromeda Galaxy — the nearest large spiral galaxy at 2.5 Mly; M42 Orion Nebula — the nearest star-forming region at 1,344 ly).

NGC/IC Catalogs (@nyx/ngc-ic)#

The New General Catalogue (NGC, 7,840 objects) and Index Catalogs (IC I and IC II, 5,386 objects) constitute the deep-sky standard reference — 13,226 objects comprising galaxies, nebulae, and clusters compiled from 19th-century visual observations.

• 13,226 Deep-Sky Objects: Full data for all NGC and IC objects including coordinates, size, magnitude, morphological type (Hubble type for galaxies, Dreyer description class for nebulae and clusters), and NGC revision notes.
• Modern Coordinate Updates: Original NGC/IC positions were measured visually and contain errors. The library uses RNGC (Revised New General Catalogue) and PGC cross-references to provide precise modern coordinates.
• Visual Descriptions: Dreyer's original visual descriptions ("vF, vS, R, BN" = very faint, very small, round, brighter nucleus) included alongside modern digital photometry.

Nebulae Database (@nyx/nebulae)#

Comprehensive catalog of emission nebulae, reflection nebulae, planetary nebulae, and dark nebulae.

• Nebula Classification: Emission nebulae glow because ionised gas emits spectral line radiation (H-alpha, O-III, S-II). Reflection nebulae scatter light from nearby stars. Planetary nebulae are the expelled outer layers of dying Sun-like stars, lit by the hot white dwarf remnant at their centre. Dark nebulae are dense molecular clouds that block background starlight.
• Ionisation Data: For emission nebulae, dominant emission lines (H-alpha at 656 nm, [O III] at 500 nm, [S II] at 672 nm), ionisation source identification, and estimated electron temperature and density from spectroscopic data.
• Astrophotography Filters: Filter recommendations for imaging each nebula — narrowband (H-alpha, O-III, S-II) for emission nebulae in light-polluted skies; broadband LRGB for reflection nebulae; which narrowband combination (e.g., Hubble palette: S-II→red, H-alpha→green, O-III→blue) produces the most informative false-colour image.

Star Clusters (@nyx/clusters)#

Separate databases for open clusters (young, loosely bound groups in the galactic disc) and globular clusters (old, dense, spherically symmetric collections of 100,000–1 million stars orbiting the galactic halo).

• Open Cluster Data: Trumpler classification (concentration, brightness range, population), estimated age and distance, associated OB stellar association, and dissolution timescale.
• Globular Cluster Data: Concentration parameter (how tightly stars pack toward the core), absolute magnitude, half-light radius, tidal radius, metallicity [Fe/H] (iron abundance relative to solar), and Galactocentric distance. Globular clusters are among the oldest objects in the galaxy — typical ages of 10–13 billion years.

Supernova Remnants (@nyx/snr)#

Database of objects left behind when massive stars explode as supernovae, including shell remnants, pulsar wind nebulae, and mixed-morphology remnants.

• SNR Types and Morphology: Shell-type (expanding blast-wave shell from the supernova; example: Tycho's SNR), pulsar wind nebula (driven by the central pulsar's relativistic wind; example: Crab Nebula), and mixed-morphology types.
• Expansion Velocities: Where measured, the current expansion velocity of the remnant and estimated time since the supernova explosion.
• Associated Historical Supernovae: Cross-references to historical supernova records (Chinese records of SN 1054, Tycho Brahe's SN 1572, Kepler's SN 1604, SN 1987A in the Large Magellanic Cloud).

Pulsars (@nyx/pulsars)#

Pulsars are highly magnetised rotating neutron stars that emit beams of electromagnetic radiation — the "lighthouses" of the cosmos.

• ATNF Pulsar Catalog Integration: The Australian Telescope National Facility Pulsar Catalog is the authoritative reference for known pulsars. The library provides typed access to pulse period, period derivative (spin-down rate), dispersion measure (column density of free electrons along the line of sight — a proxy for distance), and flux density.
• Millisecond Pulsar Identification: Millisecond pulsars (periods 1–30 ms) have been "recycled" by accretion from a companion star, spinning them back up. They are used as natural clocks for gravitational wave detection via pulsar timing arrays.
• Binary System Parameters: Orbital parameters for pulsars in binary systems — the most precise tests of general relativity come from timing binary pulsars.

Neutron Stars (@nyx/neutron-stars)#

Neutron stars are the collapsed cores of exploded massive stars — objects as massive as the Sun but only 20 km across, where matter is compressed beyond nuclear density.

• Magnetar Identification: Magnetars have magnetic fields 1,000× stronger than ordinary neutron stars (up to 10¹⁵ Gauss), producing soft gamma repeaters and anomalous X-ray pulsars.
• X-Ray Binary Classification: Neutron stars in binary systems accreting from a companion produce X-ray binaries — low-mass (companion is a low-mass star) or high-mass (companion is an OB supergiant) classifications.

Black Holes (@nyx/black-holes)#

Catalog of known and candidate black holes across stellar, intermediate, and supermassive mass ranges.

• Stellar Black Holes in X-Ray Binaries: Mass measurements from radial velocity studies of companion stars, enabling mass function calculations and black hole mass confirmation.
• Supermassive Black Holes: Central black holes in active galactic nuclei (AGN, quasars, Seyfert galaxies), with masses from stellar dynamics, reverberation mapping, and direct imaging (Event Horizon Telescope results for M87* and Sgr A*).
• Gravitational Wave Events: Cross-references to LIGO/Virgo/KAGRA merger events from the Gravitational Wave Transient Catalog (GWTC), including chirp mass, mass ratio, and event classification.

Quasars (@nyx/quasars)#

Quasi-stellar objects — extraordinarily luminous galactic nuclei powered by accretion onto supermassive black holes, visible across billions of light-years.

• Redshift Distribution: Cosmological redshift z and the corresponding look-back time and comoving distance, making quasar catalogs a tool for probing the large-scale structure of the universe.
• SDSS/BOSS Catalog Integration: Cross-references to the Sloan Digital Sky Survey quasar catalogs (DR16Q, >750,000 quasars) with photometric and spectroscopic data.

Gravitational Wave Events (@nyx/gravitational-waves)#

Events detected by LIGO, Virgo, and KAGRA interferometers — direct detections of spacetime ripples from compact binary mergers.

• GWTC Event Records: Events from the Gravitational Wave Transient Catalog with sky localisation maps (HEALPix format), source classification (BBH — binary black hole, BNS — binary neutron star, NSBH — neutron star–black hole), and posterior distributions for physical parameters.
• Sky Localisation Visualization: Render 90% credible region contours on the star map, enabling electromagnetic follow-up identification of the probable source location.

NED (NASA/IPAC Extragalactic Database) (@nyx/ned)#

The NED is the comprehensive reference for objects beyond the Milky Way — millions of galaxies, quasars, and extragalactic sources with redshifts, multi-wavelength photometry, and literature cross-references.

• Extragalactic Source Query: Query NED by position, object name, or redshift range. Returns photometric measurements across the electromagnetic spectrum (radio, infrared, optical, UV, X-ray, gamma-ray).
• Redshift Completeness: NED contains spectroscopic redshifts for millions of galaxies — enabling queries like "all galaxies within 100 Mpc within this field of view".

SDSS (Sloan Digital Sky Survey) Integration (@nyx/sdss)#

The Sloan Digital Sky Survey imaged a quarter of the sky in five filters (u, g, r, i, z) and obtained spectra for millions of objects.

• Photometric Object Catalog: Access to SDSS PhotoObj table — positions, magnitudes in all five filters, morphological classifications (point source vs extended), and object flags.
• Spectroscopic Redshifts: The SDSS spectrograph catalog contains galaxy and quasar spectra with redshift measurements, stellar parameter estimates, and spectral classifications.
• Color-Magnitude Diagrams: Generate colour-magnitude diagrams for any field from SDSS photometry — a fundamental tool for stellar population analysis and cluster member identification.

Galaxy Classification (@nyx/galaxy-classification)#

Machine learning and rule-based tools for morphological galaxy classification.

• Hubble Sequence Classification: The Hubble tuning fork diagram classifies galaxies as ellipticals (E0–E7, from round to elongated), lenticulars (S0), spirals (Sa–Sd, from tightly wound to loose), and irregular. The library implements automated classification from photometric parameters.
• GZ2 (Galaxy Zoo 2) Integration: Galaxy Zoo 2 used crowdsourced human classifications for 300,000 galaxies. The library provides access to GZ2 classification probabilities as training data for automated classifiers.
• Morphological Feature Extraction: Bar presence detection, arm count estimation, bulge-to-disc ratio, and asymmetry index from image pixel data.

Exoplanet Research#

NASA Exoplanet Archive (@nyx/nasa-exoplanets)#

The NASA Exoplanet Archive is the authoritative catalog of confirmed exoplanets — planets orbiting other stars — with 5,500+ confirmed discoveries as of 2024.

• Planetary Parameters: Orbital period, semi-major axis, eccentricity, inclination, transit depth, radius (in Earth radii), mass (in Earth or Jupiter masses), equilibrium temperature, and discovery method for each confirmed planet.
• Host Star Data: Spectral type, effective temperature, luminosity, radius, mass, age, metallicity, and distance for each host star — required to derive planetary properties from transit or radial velocity observations.
• Discovery Method Classification: Transit (transit photometry — brightness dip as planet crosses stellar disc), radial velocity (Doppler wobble of host star), direct imaging, microlensing, timing variations, and astrometry. Each method has characteristic biases that shape the discovered sample.
• Confirmed vs Candidate Status: The archive distinguishes confirmed planets (multiple independent observations) from candidates (single detection, awaiting confirmation) — the library exposes this status.

Open Exoplanet Catalog (@nyx/open-exoplanets)#

The community-maintained Open Exoplanet Catalog augments the NASA archive with additional data fields, exomoon candidates, and more frequent updates.

• Exomoon Candidates: Tentative detections of moons orbiting exoplanets — a nascent field with only a handful of candidates. The library flags candidates with their confidence level and detection method.
• Multi-Planet System Architecture: System-level views showing orbital configurations, mean-motion resonance relationships, and stability analyses for multi-planet systems.

Planetary Habitability Analysis (@nyx/habitability)#

Quantitative assessment of the potential habitability of exoplanets and their host systems.

• Circumstellar Habitable Zone (HZ): The range of orbital distances around a star where liquid water could exist on a rocky planet's surface, assuming Earth-like atmospheric pressure and composition. Computed using Kopparapu et al. (2013) parametrisations: conservative HZ (runaway greenhouse inner edge to maximum greenhouse outer edge) and optimistic HZ (recent Venus inner edge to early Mars outer edge).
• Earth Similarity Index (ESI): A composite metric comparing a planet to Earth on four parameters: radius, density, escape velocity, and equilibrium temperature. ESI = 1 for Earth; ESI > 0.8 is considered potentially Earth-like.
• Stellar Habitability Constraints: Active M-dwarf stars produce frequent superflares that may strip atmospheres from close-in HZ planets; F-type stars have shorter main-sequence lifetimes that may not allow time for complex life to evolve. The library scores stellar properties for habitability impact.
• Atmospheric Retention: Estimate whether a planet of given mass and temperature can retain various atmospheric species (H, He, H2O, CO2, N2) using Jeans escape velocity calculations.

Solar System#

Planet Ephemerides (@nyx/planets)#

High-precision positions of all eight planets and major dwarf planets at any epoch.

• Meeus Algorithm Implementations: Jean Meeus's "Astronomical Algorithms" provides analytic approximations to planetary positions accurate to arcsecond level — sufficient for all amateur and most professional positional astronomy applications.
• JPL Horizons Integration (@nyx/horizons): For highest precision, JPL's HORIZONS system generates ephemerides directly from numerical integration of the solar system. The library wraps the HORIZONS API for programmatic access to position vectors, velocities, and observer-relative quantities for any solar system body at any epoch.
• Apparent vs. True Positions: The library correctly distinguishes apparent position (accounting for light travel time — where the object was when the light now arriving was emitted) from true/geometric position (where the object is now), applying the appropriate correction based on context.
• Moon Data (@nyx/moons): All known natural satellites of the solar system planets — orbital elements, physical parameters, and ephemerides for the major moons of Jupiter, Saturn, Uranus, and Neptune.

Minor Planets — MPC Database (@nyx/mpc)#

The Minor Planet Center (MPC) maintains the definitive catalog of asteroids, trans-Neptunian objects, and other small bodies — currently 600,000+ numbered objects.

• Orbital Element Database: Full MPC orbital element files (MPCORB.DAT) parsed and queryable — semi-major axis, eccentricity, inclination, node, argument of perihelion, mean anomaly, epoch, and absolute magnitude H for each object.
• Taxonomy Integration: SMASSII and Bus-DeMeo asteroid taxonomic classifications (C-type carbonaceous, S-type silicaceous, M-type metallic) from spectrophotometric data.
• Proper Elements: Osculating orbital elements are perturbed by planetary gravity and vary over time; proper elements are long-term average values that define membership in asteroid families (collisional fragments of larger parent bodies).

Near-Earth Objects (@nyx/neo)#

Asteroids and comets with perihelia less than 1.3 AU — the population that occasionally intersects Earth's orbit.

• NEO Classification: Atiras (orbits entirely inside Earth's orbit), Atens (semi-major axis < 1 AU, extends beyond Earth's orbit), Apollos (semi-major axis > 1 AU, semi-major axis crosses Earth's orbit), Amors (perihelion between 1.017 and 1.3 AU — approaching but not currently crossing Earth's orbit).
• Potentially Hazardous Asteroids (PHAs): Objects with MOID (Minimum Orbit Intersection Distance) < 0.05 AU and absolute magnitude H < 22 (diameter ≥ 140 m). The library provides the current PHA list with impact probability assessments from the CNEOS Sentry system.
• Close Approach Predictions: Upcoming close approaches within 0.2 AU, with date, nominal miss distance, and uncertainty range from JPL CNEOS.

Comets (@nyx/comets)#

Active comets with current ephemerides and visibility predictions.

• Current Comet List: Active periodic and long-period comets with orbital elements from the MPC, including recent perturbed elements for objects approaching perihelion.
• Coma and Tail Growth Models: Empirical brightness models (H, G parameters) predict visual magnitude as a function of heliocentric and geocentric distance. Coma and tail length predictions based on historical parallels.
• Historical Comet Records: Halley's Comet apparition records dating back to 240 BC, enabling time-travel visualisation of historically recorded cometary appearances.

Spacecraft Catalog (@nyx/spacecraft)#

Currently active and historical spacecraft missions with trajectory data.

• Active Mission Tracking: NASA/ESA/JAXA/CNSA mission status with current position (for interplanetary spacecraft, derived from JPL HORIZONS), primary science objectives, and key instrument status.
• Trajectory Visualization: Heliocentric orbital plots of spacecraft trajectories superimposed on planetary orbits, showing gravity assist manoeuvres and current position relative to planets.

Orbital Mechanics#

The orbital mechanics libraries handle the mathematical core of the domain: converting between different ways of describing an orbit, propagating positions forward and backward in time, and applying the corrections needed to obtain accurate observable coordinates from raw calculations.

Ephemeris Engine (@nyx/ephemeris)#

High-precision solar system position calculations implementing Meeus algorithms.

• Sun and Moon Positions: Accurate to arcsecond level using the full VSOP87 (Variations Séculaires des Orbites Planétaires) analytical theory for the sun and ELP 2000-82 for the moon — the standard precision algorithms used in professional ephemeris software.
• Planet Positions: All eight planets computed using VSOP87 heliocentric coordinates reduced to geocentric apparent positions with full corrections for light travel time, annual parallax, precession, nutation, and aberration.
• Eclipse Prediction: Solar and lunar eclipse prediction using the Besselian element method. Solar eclipse type (total, annular, partial, hybrid), path of totality/annularity with ground-track coordinates, and umbral/penumbral contact times for any observer location.
• Transit of Inner Planets: Mercury and Venus transit predictions — the last Venus transits were 2004 and 2012; the next pair won't occur until 2117 and 2125, but Mercury transits every ~13 years.

Positional Astronomy (@nyx/positional)#

Observer-relative calculations: altitude, azimuth, rise/set times, and sky conditions. This library bridges the gap between the solar-system calculations in @nyx/ephemeris and what an observer at a specific location actually sees.

• Rise, Transit, and Set Times: Topocentric rise and set times for any object, corrected for atmospheric refraction (which lifts objects ~34 arcminutes when on the horizon, making them visible slightly longer than geometrically predicted), semi-diameter, and parallax where applicable.
• Sidereal Time: Local Mean Sidereal Time (LMST) — the right ascension of the meridian — is the fundamental link between Universal Time and the sky. An object transits (reaches highest altitude) when its right ascension equals the LMST.
• Atmospheric Refraction Correction: The standard refraction formula (based on Meeus) lifts objects near the horizon. The true altitude of an object on the horizon is approximately 34 arcminutes below what's visible due to refraction bending light around the curve of the atmosphere.
• Parallactic Angle: The angle between the direction "up" (toward the zenith) and "north" (toward the celestial north pole) at an object's current position — important for orienting CCD cameras and tracking field rotation in alt-az mounts.

Orbital Elements (@nyx/orbital)#

Tools for propagating orbital elements and computing derived quantities.

• Kepler Equation Solver: Iterative (Newton-Raphson) and closed-form solutions to Kepler's equation M = E − e sin E for the eccentric anomaly E, enabling position calculation from mean anomaly M for any eccentricity.
• State Vector Propagation: Convert between orbital elements and Cartesian state vectors (position + velocity in 3D space). Propagate state vectors using two-body (analytical) and n-body (numerical) integrators.
• Orbital Perturbation Models: First-order perturbations from planetary gravitation applied to asteroid and comet orbits for improved short-arc predictions — important for newly discovered objects before a full orbit is determined.

Coordinate Transforms (@nyx/coordinates)#

Implementations of all standard astronomical coordinate system transformations.

• Epoch Transformations: Precession from any epoch to J2000.0 and back, using IAU 2006 precession theory. This is required when using historical catalogs referenced to B1950.0 or other older epochs.
• Nutation and Aberration: Short-period nutation corrections (18.6-year nodal precession period, up to ±9.2 arcseconds) and stellar aberration (apparent displacement of up to ±20.5 arcseconds due to Earth's 30 km/s orbital velocity).
• Parallax Correction: Annual parallax (displacement of nearby stars as Earth orbits the Sun — up to 0.77 arcseconds for the nearest star, Proxima Centauri) and diurnal parallax (displacement of the Moon due to observer's position on Earth's surface — up to ±57 arcseconds for the Moon).

Time Systems (@nyx/time)#

Complete implementation of all astronomical time standards and their interconversions. Astronomy uses several distinct time scales for good physical reasons, and mixing them silently produces errors that are difficult to diagnose.

• Julian Date and MJD: Julian Date (JD) is the continuous count of days and fractions since noon UT on 1 January 4713 BC — the astronomers' universal time coordinate. Modified Julian Date (MJD = JD − 2,400,000.5) starts from midnight of 17 November 1858 for a more compact representation.
• Time Scale Conversions: UTC (Coordinated Universal Time — basis of civil time, with leap seconds), UT1 (astronomical universal time based on Earth's rotation), TAI (International Atomic Time — no leap seconds), TDB (Barycentric Dynamical Time — uniform time for solar system calculations), TT (Terrestrial Time — successor to Ephemeris Time). Each scale has a specific purpose in astronomical computation.
• Leap Second Management: Up-to-date IERS leap second table used for UTC-to-TAI conversions. The library handles leap second announcements and graceful handling of the leap second boundary.
• Delta-T Tables: Historical and predicted values of ΔT (the difference between TT and UT1, reflecting irregular variations in Earth's rotation rate). Required for computing solar system positions at historical epochs — without ΔT correction, eclipse path predictions for ancient events would be off by hundreds of kilometres.

Sky Rendering and Visualization#

Sky Renderer (libs/nyx/renderer/*)#

The renderer is a layered WebGL/Three.js pipeline split across 12 packages to allow applications to include only the visual layers they need. The packages are: @nyx/renderer-core, @nyx/renderer-stars (published as @nyx/star-colors), @nyx/renderer-background, @nyx/renderer-planets, @nyx/renderer-galaxies, @nyx/renderer-nebulae, @nyx/renderer-clusters, @nyx/renderer-exotic, @nyx/renderer-hdr, @nyx/renderer-lod, @nyx/renderer-scale, and @nyx/renderer-post-processing.

• Multi-Million Star Rendering: WebGL geometry instancing renders up to 10 million stars simultaneously at 60 fps on desktop hardware. Each star is rendered as a textured quad with angular size proportional to magnitude and colour matched to B-V index.
• Milky Way Band: The diffuse Milky Way band is rendered from a high-resolution texture (derived from 2MASS all-sky survey infrared data) with realistic brightness distribution and colour gradient across the galactic plane.
• Map Projections: Stereographic, gnomonic, orthographic, Mercator, and Aitoff-Hammer projections — each with different distortion characteristics suited to different use cases. Gnomonic projection is preferred for telescope planning because it renders great circles as straight lines.
• Deep-Sky Object Rendering: NGC/IC objects rendered as scaled symbols (galaxies as ellipses, clusters as circles, nebulae as outlined regions) with orientation matching the object's position angle on the sky.
• Constellation Art: Optional historical constellation artwork — the traditional mythological figures drawn behind the star patterns — for the 88 IAU constellations in multiple artistic styles.
• Planet Rendering: Planets rendered with phase (showing illuminated fraction based on current geometry), approximate disc size scaled to angular diameter, and ring system for Saturn. Planet glyphs update position in real time.

Visualization Library (@nyx/visualization, @nyx/galaxy-distribution)#

Scientific data visualisation tools for astronomical data.

• Colour-Magnitude Diagrams (HR Diagrams): The Hertzsprung-Russell diagram plots stellar luminosity vs. effective temperature. Main sequence, red giant branch, horizontal branch, and white dwarf cooling sequence are visually identified. Essential for understanding stellar evolution and cluster age determination.
• Spectral Energy Distributions: Multi-wavelength flux plots from radio through gamma-ray for extragalactic objects, showing the characteristic spectral signatures of different source types (synchrotron radiation peaks in radio/X-ray, thermal emission peaks in optical/IR).
• Orbital Diagram Plots: 2D and 3D orbital plots for solar system objects — heliocentric orbital ellipses, positions at specified dates, and animated orbital motion.
• All-Sky Maps: Mollweide and Aitoff equal-area projections for displaying whole-sky surveys, LIGO sky maps, and cosmic microwave background data.
• Sky Chart Generation: Publication-quality finder charts and observing charts generated as SVG or PNG, with configurable magnitude limit, field size, and label density.

Widgets (libs/nyx/widgets/*)#

Embeddable UI widgets for building astronomy web applications, shipped as three packages: @nyx/widget-iss-tracker, @nyx/widget-moon-phase, and @nyx/widget-star-map.

• Altitude/Time Chart Widget: Animated chart showing how an object's altitude changes across a night, with twilight zones, meridian marker, and optimal observation window highlighted.
• Moon Phase Widget: Animated lunar phase calendar for the current month, with exact phase times and age.
• Planet Positions Widget: Compact display of current planet positions, showing which are visible at night and when they rise/set.
• Object Info Card: Rich information card for any celestial object — image, basic parameters, visibility tonight, and observing notes.
• Observing Planner Widget: Interactive night-plan visualiser showing an observing list's targets distributed across the night by altitude and optimal observation window.

Real-Time Data#

Real-Time Satellite Tracking (@nyx/realtime-satellites, @nyx/realtime-neo)#

Satellite positions change fast enough that a polling-based approach quickly falls behind. These libraries maintain live state from TLE data, updating positions continuously.

• ISS and Starlink Tracking: Real-time position of the International Space Station and all Starlink satellites updated every 10 seconds from NORAD TLE data. ISS position accurate to ~1 km.
• 25,000+ Satellite Database: The full active satellite catalog from CelesTrak NORAD TLE data, covering scientific, weather, communications, navigation, military, and debris objects. Updated every 4 hours.
• Pass Prediction: Upcoming ISS and satellite passes for any observer location — time of appearance, direction, peak altitude, duration, and maximum magnitude. Essential for planning naked-eye satellite observations and astrophotography avoidance.
• Iridium Flare Prediction: Before the Iridium constellation replacement, Iridium satellites produced brief, brilliant flares (up to magnitude −8 — brighter than Venus). The legacy Iridium-1 constellation continues to produce occasional flares; the library predicts their timing, duration, and magnitude.
• Starlink Train Tracking: During initial deployment phases, Starlink launches produce "trains" of closely spaced satellites that generate astrophotography interference. The library predicts train passes.
• Reentry Prediction: Objects in decaying orbits are flagged with estimated reentry windows and ground-track projections.

Real-Time Solar Data (@nyx/realtime-solar)#

• Solar Position: Real-time solar position (altitude, azimuth, declination, right ascension) updated every second, including solar noon, civil/nautical/astronomical twilight times.
• Solar Activity: Integration with NOAA Space Weather Prediction Center for solar flare events (X-ray flux), coronal mass ejection (CME) alerts, and geomagnetic storm (Kp index) notifications — relevant to aurora predictions and satellite drag.

Astronomical Events (@nyx/events)#

Comprehensive prediction engine for all major celestial events. Rather than requiring each application to reimplement eclipse geometry or meteor shower calendars, @nyx/events centralises all event prediction behind a single typed interface.

• Solar and Lunar Eclipses: Total, partial, annular, and hybrid solar eclipses with path-of-totality ground-track coordinates, contact times (C1–C4), and maximum eclipse characteristics at any observer location. Penumbral, partial, and total lunar eclipses with umbral magnitude and contact times.
• Planetary Conjunctions and Oppositions: Dates when planets reach conjunction (same right ascension as the sun — typically unobservable) or opposition (opposite the sun in the sky — the best observing geometry, closest to Earth for outer planets). Closest approach dates and minimum separation.
• Meteor Shower Predictions: All major annual meteor showers — Perseids (August), Leonids (November), Geminids (December), Quadrantids (January), etc. — with predicted zenithal hourly rate (ZHR), radiant altitude at midnight, parent body comet/asteroid, and optimal viewing window accounting for moonlight.
• Solstices and Equinoxes: Exact moments of the four solar seasonal markers, with Sun's declination, day length, and solar noon altitude at any latitude.
• Moon Phases: Precise times for new, first quarter, full, and last quarter moon; lunar apogee and perigee (closest/furthest distance in the elliptical orbit — affects tidal range and apparent lunar size).
• Planetary Transits: Mercury and Venus transit predictions, including ingress/egress contact times and central transit duration.
• Occultations: Moon occultations of stars and planets, and asteroid occultations of stars (used to measure asteroid sizes and probe atmospheres), with graze line path predictions.

Observation Planning (@nyx/observation-planner, @nyx/time-travel)#

• Night Visibility Planner: For any date and observer location, lists all catalog objects that will be above the horizon during darkness, with their peak altitude, transit time, and estimated visibility rating (factoring aperture, sky darkness, and moon phase).
• Observing List Builder: Create, save, and share curated target lists. Each target entry records notes, estimated observation time, difficulty rating, and whether the object has been observed.
• Bortle Dark-Sky Scale: John Bortle's nine-class scale rates sky darkness from Class 1 (truly dark sky — zodiacal light visible even at midday, Gegenschein obvious) to Class 9 (inner-city sky — only the moon, planets, and brightest stars visible). The library estimates the observer's Bortle class from location and computes limiting magnitude.
• Sky Darkness Calculator: Calculate sky brightness (in magnitudes per square arcsecond) from location, time, and moon phase, enabling realistic assessment of deep-sky visibility.
• Equipment Filter: Filter catalog objects to show only those achievable with specified equipment — e.g., "show only objects brighter than magnitude 12 and larger than 5 arcminutes for a 200mm f/8 Dobsonian".
• Session Log: Record observing session notes — date, site conditions, equipment used, objects observed, sketches, and image references — against a structured session record.

Time Travel (@nyx/time-travel)#

• Historical Sky Simulation: Render the night sky for any date and observer location in the past or future — from the construction of Stonehenge to 10,000 years in the future, limited only by the accuracy of stellar proper motion models and planetary theory.
• Stellar Proper Motion Projection: Stars are not fixed — proper motion accumulates over millennia. Simulate how the constellations appeared to ancient astronomers and how they will appear to far-future observers. Orion, for example, will be unrecognisable in 100,000 years.
• Historical Event Simulation: Reproduce famous historical astronomical events — the supernova of 1054 AD that Chinese astronomers recorded (now the Crab Nebula), the Star of Bethlehem conjunction candidates, ancient solar eclipses whose paths of totality are recorded in cuneiform tablets.
• Calendar Systems: Support for Gregorian, Julian (used in Europe before 1582), proleptic Gregorian, and Julian Date inputs, enabling correct date handling for historical events before the Gregorian calendar reform.

Telescope Control and Astrophotography#

Telescope Control (@nyx/telescope)#

• ASCOM Alpaca Integration: @nyx/telescope controls telescopes through the ASCOM Alpaca REST API — createAlpacaController(host, port) connects to an Alpaca device for slewing, syncing, tracking control, park/unpark, and pulse guiding.
• INDI Protocol Support: INDI (Instrument Neutral Distributed Interface) is the cross-platform alternative — a client-server architecture where INDI drivers run as a server and the Nyx library connects as a client.
• GoTo Targeting: Slew the telescope to any selected catalog object with one click — coordinates are converted to the mount's native coordinate system (alt-az or equatorial), accounting for sidereal tracking rate, pointing model corrections, and atmospheric refraction.
• Pointing Model and Alignment: Sync the mount's pointing model from measured star positions — each alignment star corrects systematic pointing errors. Multi-star alignment builds a whole-sky correction model.
• Plate Solving Integration: Astrometric plate solving (AstrometryNet, ASTAP, or PS3) identifies the precise coordinates of any captured image by pattern-matching stars against a reference catalog, enabling blind goto and automated re-centering.
• Meridian Flip Management: Equatorial mounts must "flip" (rotate 180°) when a tracked object crosses the meridian, or the telescope would hit the pier. The library predicts the optimal flip time and executes it automatically.
• Focus Control: Motorised focuser control with configurable step sizes; autofocus routines using half-flux radius (HFR) or full-width half-maximum (FWHM) as the focus quality metric.

Astrophotography#

• Imaging Sequence Planning: Define multi-target, multi-filter imaging queues — object, filter, exposure duration, frame count, dithering strategy — executed automatically across a night.
• Live Stacking: Accumulate frames in real time as they arrive from the camera, performing alignment (sub-pixel shift and rotation correction) and integration (mean, median, or σ-clipping) on the fly. Faint deep-sky detail emerges progressively as frames accumulate.
• Calibration Frame Management: Automated collection and application of dark frames (camera noise at same temperature and exposure time), flat frames (illumination uniformity correction), and bias frames (electronic offset). Calibration library management ensures the correct frames are applied to each light frame.
• Polar Alignment Tools: Iterative polar alignment procedure — slew to three positions near the celestial pole, measure the pole position error from the drift in each, and compute the required alt/az adjustment to the mount's polar axis.
• Image Analysis Metrics: Full-width half-maximum (FWHM) of stellar point spread functions (measuring atmospheric seeing and focus quality), half-flux radius (HFR), signal-to-noise ratio (SNR) per sub-frame, background gradient measurement, and star count.

Educational Features (@nyx/lesson-framework, @nyx/quiz-system, apps/nyx/education/*)#

• Astronomy Courses: Structured multi-module courses from introductory ("What is a star?") through intermediate (stellar evolution, cosmology) to advanced (spectroscopy, exoplanet detection methods). Each module includes narrative text, interactive simulations, and quiz assessments.
• Guided Sky Tours: Thematic itineraries through the night sky — "Tonight's Best Objects", "Mythology Tour" (following the narrative connections between constellations), "Messier Marathon" (attempting all 110 Messier objects in one night), and "Deep Sky Hunter" (galaxies and galaxy clusters only).
• Stellar Evolution Simulator: Interactive visualisation of a star's life cycle from formation in a molecular cloud through main sequence, giant phase, and endpoint (white dwarf, neutron star, or black hole) — parameterised by initial stellar mass.
• Scale Models: Interactive logarithmic-scale visualisations of the solar system, the Milky Way galaxy, the Local Group, and the observable universe — helping build genuine intuition for the enormous size and emptiness of cosmic structures.
• Quiz and Assessment System: Multiple-choice and identification quizzes tied to specific course modules, with adaptive difficulty and progress tracking.
• Spectroscopy Education: Interactive spectrograph simulator showing how astronomers measure composition, temperature, radial velocity, and magnetic field strength from stellar spectra.

Multi-Cultural Constellation Database (@nyx/constellations)#

The constellations library provides a comprehensive, culturally inclusive sky map that goes far beyond the 88 Western IAU boundaries — representing six distinct astronomical traditions from cultures that developed entirely independent star lore over millennia.

• IAU (International Astronomical Union) — Official Modern Constellations: All 88 modern constellation boundaries as defined by the IAU in 1930, with precise boundary coordinates, the included bright stars, adjacent constellation relationships, and standard abbreviations. The IAU boundaries cover the entire celestial sphere without gaps.
• Chinese Astronomical Tradition: The Three Enclosures (Purple Forbidden Enclosure, Supreme Palace Enclosure, Heavenly Market Enclosure) plus the 28 Lunar Mansions (Xiu — the stations of the Moon through the Chinese zodiac belt) with their associated star deities, auspicious meanings, and cultural context. Chinese astronomy developed independently over 4,000 years and contains star groupings and significance entirely distinct from Greek tradition.
• Egyptian Astronomical Tradition: The 36 Decans — groups of stars that the ancient Egyptians used to divide the night into hours by observing which decan rose heliacally at dawn — along with the circumpolar stars of the northern sky and southern hemisphere constellations documented in the Dendera zodiac and tomb ceiling paintings.
• Polynesian Navigation Star Traditions: Navigation stars and their cultural significance across Hawaiian, Tahitian, and Māori traditions. Polynesian navigators used star rising and setting points to navigate thousands of kilometres of open ocean without instruments — stars that are merely cultural curiosities in Western astronomy were precision navigation tools in Pacific traditions.
• Norse and Germanic Astronomical Traditions: Germanic and Viking sky lore, including the cosmological significance of Orion as Frigg's distaff, the Milky Way as Bifröst (the rainbow bridge to Asgard), and star groupings used in Northern European agricultural and seasonal calendar-keeping.
• Indigenous American Traditions: Constellation and star traditions from Lakota, Navajo, Pawnee, Inca, and Ojibwe cultures — including the Pawnee's sophisticated sky charts recorded on elk hide and the Inca's "dark cloud constellations" (the dark patches of the Milky Way that their tradition treated as equally significant as the star patterns, representing animals in the shadows between stars).
• Visible Constellations by Observer Location: Real-time calculation of which constellations from any tradition are currently above the horizon for a given observer location and time — enabling culturally personalised sky tours.
• Cross-Cultural Star Identification: For any star, surface all the names, roles, and cultural significance it carries across different traditions — showing how Rigel, Aldebaran, or Antares appeared to ancient Egyptians, Arabic astronomers, Polynesian navigators, and indigenous peoples as entirely different objects in entirely different stories.

Constellation Mythology (@nyx/mythology)#

• All 88 IAU Constellations: Origin mythology, traditional asterism boundaries, included bright stars, and adjacent constellation relationships for all 88 modern constellation boundaries defined by the IAU in 1930.
• Multi-Cultural Traditions: Greek/Roman traditions (the canonical Western zodiac and figures), Chinese Lunar Mansions (28 Xiu and their associated star deities), Polynesian navigation stars and their cultural significance, Arabic star names (most traditional star names in modern use are Arabic in origin — Aldebaran means "the follower" in Arabic, Betelgeuse derives from "shoulder of Orion," Fomalhaut means "mouth of the southern fish"), and indigenous constellation traditions from multiple cultures.
• AI-Narrated Mythology Stories: Text-to-speech narration of mythology associated with selected constellations and stars, allowing eyes-free listening while observing at the eyepiece rather than reading a screen in the dark.
• Historical Star Name Etymology: For each traditional star name, the language of origin (Arabic, Greek, Latin, etc.), original meaning, and historical evolution of the name's usage across cultures and centuries.

Audio and Narration (@nyx/audio-sonification, @nyx/audio-ambient)#

• AI Voice Narration: Text-to-speech narration of object descriptions, mythology, guided tour commentary, and course content — enabling eyes-free operation while observing at the eyepiece or in VR.
• Sonification: Astronomical data mapped to sound — stellar brightness to volume, spectral type to pitch, pulsation period to rhythm. Allows perception of data relationships through audition, accessible to visually impaired users.
• Ambient Cosmic Soundscapes: AI-generated ambient audio textures inspired by different celestial environments — the crackling radio emission of a pulsar, the spectral signature of a stellar nursery rendered as musical harmony, the 2.7K CMB as a faint hiss.

Social and Community#

• Observing Session Sharing: Share observing session logs, target lists, and annotated sky charts with other users. Import community-contributed observing lists as starting points for your own sessions.
• Observer Location Network: Optional public location sharing enabling discovery of other observers in your area — coordinate joint observing sessions or compare notes on the same object from nearby sites.
• Observation Image Gallery: A gallery linking astrophotography images to the specific catalog entries (NGC 6992, M51, etc.) they capture, creating a crowdsourced imaging encyclopedia.
• Community Astronomy Content: User-contributed mythology notes, cultural astronomy content, and observation reports attached to specific objects.

Gamification#

• Observer Rank System: Progressive observer ranks — Stargazer → Astronomer → Observer → Deep-Sky Hunter → Master Observer — earned by logging observations, completing challenges, and contributing community content.
• Achievement Badges: First Planet, First Double Star, Messier Marathon Complete, Solar Eclipse Witness, Comet Observer, Variable Star Monitor, and dozens more achievement badges tied to specific observing milestones.
• Observing Challenges: Curated object sets — Astronomical League observing programs, Herschel 400, Double Star Club — tracked against logged observations with printable completion certificates.

API and Integration (@nyx/client, @nyx/api-client, @nyx/telescope, @nyx/stellarium)#

• REST API Server: Hono-based REST API (OpenAPIHono) with @hono/zod-openapi. Endpoints cover objects (catalog queries), ephemeris (position, current position, rise/set), events (range, upcoming, types), and satellites (list, categories, pass predictions).
• API Key Tiers: Tiered fixed-window rate limiting — anonymous 60 rpm, free 300 rpm, pro 1,000 rpm, enterprise 5,000 rpm. Keys may be revoked, expired, and feature-scoped through a Postgres api_keys table; anonymous access is permitted with the most restrictive limits.
• WebSocket Subscriptions: Real-time position updates, satellite pass events, and event/visibility alerts delivered over a WebSocket server attached to the same process — enabling live sky-map applications that update without polling. Per-tier connection and subscription budgets apply.
• TypeScript Client (@nyx/client): Hand-written, fully typed TypeScript client for the API endpoints (client.objects, client.ephemeris, …).
• OpenAPI-Typed Client (@nyx/api-client): An alternative client whose request/response types are generated from the OpenAPI document.
• Telescope and Planetarium Integrations: @nyx/telescope controls telescopes over ASCOM Alpaca and INDI; @nyx/stellarium imports/exports Stellarium bookmarks, observing lists, and DSO catalogs; @nyx/planetarium provides further planetarium-software interoperability.
• RFC 7807 Problem Details: All API errors return RFC 7807 Problem Details JSON for consistent error handling across client implementations.

A separate @nyx/lilith-integration package bridges Nyx to the Lilith consciousness domain — see the Cross-Domain section below.

Data Storage (@nyx/database)#

The database library defines the persistent schema that the API and pipeline workers share. Using Zod models as the schema source of truth means runtime validation and static types stay in sync with the database structure.

• PostgreSQL Schema: @nyx/database defines the persistent schema as Zod object models (stars, exoplanets, solar-system planets, galaxies, nebulae, star clusters, catalog cross-references, orbital elements, TLE elements, ephemeris entries, eclipse data, celestial events, observation logs, saved views, custom annotations, educational tours, observing lists, achievements, user preferences) and ships nine Knex migration files that create the corresponding ~36 tables.
• Catalog Cross-Reference: A dedicated catalog_cross_references table plus a name_aliases table resolve objects across catalogs and surface common, Bayer, Flamsteed, Arabic, Chinese, and indigenous names.
• Computed-Event Persistence: The event-calculator pipeline upserts predicted conjunctions and eclipses into the celestial_events table.
• API Key Registry: An api_keys table stores SHA-256-hashed keys with tier, owner, feature scope, and expiry/revocation columns.

The earlier feature document described Drizzle ORM, pgvector semantic search, HEALPix-partitioned tables, and Q3C/pgSphere spatial extensions. The current @nyx/database uses Knex migrations with Zod schema models; those ORM/extension claims have been removed.

Cross-Domain Bridge (@nyx/lilith-integration)#

@nyx/lilith-integration connects Nyx's cosmic imagery to the Lilith consciousness domain as a cosmic-meditation content and session library. It is not an event adapter and does not expose astronomical data to LLM agents.

The boundary exists at the content level rather than the data level: Lilith receives curated, human-readable meditation material rather than ephemeris data or catalog objects. This means Lilith does not need to know how to compute a stellar position or query a TLE, only how to animate a breath pattern or progress through a meditation exercise.

• Cosmic Visualizations: Eight guided visualizations (COSMIC_VISUALIZATIONS) across themes such as stellar birth, the cosmic void, galactic flow, planetary consciousness, universal expansion, quantum connection, light journeys, and cosmic time scales — each pairing a visualization script with guidance and a real scientific fact.
• Inner/Outer Space Parallels: Eight SPACE_PARALLELS drawing connections between a consciousness concept and a cosmic phenomenon (the silent mind and the cosmic void, the unconscious and dark matter, awareness arising and star formation).
• Consciousness Expansion Sessions: Six exercises (CONSCIOUSNESS_EXERCISES) spanning the awareness phases grounding → centering → expanding → cosmic_awareness → integration → return.
• Cosmic Breath Patterns: Five timed breath patterns (BREATH_PATTERNS) — stellar pulse, galactic wave, cosmic expansion, quantum stillness, light speed.
• Session Manager: LilithBridgeManager runs a meditation session, animating breath phases and progressing exercises, and emits lifecycle events (session_started, phase_changed, breath_cycle_completed, …).

Applications (apps/nyx/*)#

The capability libraries above are composed into 22 packaged applications: six top-level applications plus two directory groups (education, tools) of individually packaged sub-applications.

Top-level applications (6):

• apps/nyx/api (@nyx/api) — the Nyx Astronomy REST + WebSocket API: programmatic access to celestial objects, ephemeris, astronomical events, and satellite data for every other surface and for external consumers.
• apps/nyx/star-map (@nyx/star-map) — the interactive web star map and planetarium (the largest app, ~189 source files): catalog rendering, constellations, filters, collections, bookmarks, audio, time-travel, tonight view, journal, and guided controls.
• apps/nyx/vr-planetarium (@nyx/vr-planetarium) — the immersive VR planetarium: React-Three-Fiber + WebXR scenes and narrated sky tours.
• apps/nyx/ar-sky (@nyx/ar-sky) — the augmented-reality sky viewer: point a device at the sky to identify and label objects in real time, with an observing assistant.
• apps/nyx/mobile (@nyx/mobile) — the mobile star-map app for on-location observation, with offline storage via idb-keyval.
• apps/nyx/pipelines (@nyx/pipelines) — the astronomical data-pipeline workers (TLE updater, catalog syncer, ephemeris generator, event calculator).

Education applications (apps/nyx/education, 12): five courses (fundamentals, solar-system, stellar, galactic, cosmology), two challenges (star-identification, orbital-mechanics), and five interactive demos (HR diagram, spectroscopy, distance ladder, light speed, gravity well).

Tools applications (apps/nyx/tools, 4): @nyx/astrophotography, @nyx/light-curves, @nyx/observation-planner, @nyx/orbit-determination.

Kalika vs. Nyx Boundary#

Kalika owns mathematics and physics research tooling. Nyx owns astronomy education, the observatory and sky-map platform, ephemeris computation, celestial experience features, and the telescope/hardware layer. If a feature is primarily about mathematical or physical theory divorced from observable sky objects, it belongs in Kalika. If it is about something you can point a telescope at or observe from a dark-sky site, it belongs in Nyx.

Source Grounding#

This feature map is scoped to apps/nyx/*, libs/nyx/*, deploy/nyx/*, and TODOS/phase-21.md. It captures catalogs, coordinates, constants, ephemeris, positional astronomy, orbital mechanics, real-time data, events, mythology, time and time-travel, the renderer/visualization/widget package groups, analysis, education, audio, client SDKs, telescope/planetarium integrations, pipelines, the cosmic-meditation Lilith bridge, and the AR/VR/mobile/star-map applications. Package names and counts (75 libraries, 22 applications) were verified against the package.json files; the database section and the @nyx/lilith-integration description were corrected against source. Sections on social/community and gamification describe product-level features built on the observation_logs, observing_lists, achievement_definitions, and user_achievements tables defined in @nyx/database.