Eve library

Nyx Architecture

Guide

Revision 1

On this page

Canonical source: the canonical architecture document for this domain is deep-dive/architecture.md, rendered in the docs center. This file is its operational companion (service topology, APIs, schemas, runtime detail) — reconciled by linking, not duplicated (§2, §13).

System Architecture for the Cosmic Observatory Platform

This document describes the technical architecture of the Nyx domain, covering service topology, data flows, database schemas, API design, and cross-domain dependencies.


Table of Contents#

  1. System Overview
  2. Service Architecture
  3. Application Layer
  4. Library Layer
  5. API Architecture
  6. WebSocket Architecture
  7. Data Pipeline Architecture
  8. Database Schema
  9. Data Flow
  10. Cross-Domain Dependencies
  11. Deployment Architecture
  12. Technology Stack

System Overview#

Nyx is a full-stack astronomical education and observation platform. The architecture is designed around three core principles:

  1. Computational accuracy -- Ephemeris, coordinate transforms, and time systems are implemented from peer-reviewed astronomical algorithms (Meeus, IAU standards, JPL-derived elements).
  2. Real-time delivery -- WebSocket channels push position updates, satellite passes, and event alerts at configurable intervals.
  3. Modular library composition -- 26 libraries provide independent capabilities that compose into 8 applications.
text
                         ┌────────────────────────────────┐
                         │         CLIENTS                 │
                         │  Web  Mobile  AR  VR  CLI       │
                         └──────────────┬─────────────────┘
                                        │
                    ┌───────────────────┬┴──────────────────┐
                    ▼                   ▼                    ▼
              ┌───────────┐    ┌──────────────┐    ┌──────────────┐
              │  REST API  │    │  WebSocket   │    │   Static     │
              │  (Hono)    │    │  (ws)        │    │  Star Map    │
              │  Port 3000 │    │  /ws         │    │  (Vite)      │
              └─────┬──────┘    └──────┬───────┘    └──────────────┘
                    │                  │
              ┌─────┴──────────────────┴──────────────────┐
              │              SERVICE LAYER                  │
              │  Ephemeris | Objects | Events | Satellites  │
              └─────┬──────────────────────────────────────┘
                    │
              ┌─────┴──────────────────────────────────────┐
              │              LIBRARY LAYER                   │
              │  @nyx/ephemeris  @nyx/coordinates  @nyx/time │
              │  @nyx/catalogs   @nyx/events      @nyx/types │
              └─────┬──────────────────────────────────────┘
                    │
              ┌─────┴──────────────────────────────────────┐
              │              DATA LAYER                      │
              │  PostgreSQL (pgvector) │ Redis │ File System │
              └────────────────────────────────────────────┘

Service Architecture#

Applications (8)#

Application Directory Type Port Framework Description
API apps/nyx/api Server 3000 Hono + OpenAPI REST + WebSocket API for all astronomical data
Star Map apps/nyx/star-map Web App 5173 Vite + WebGL Interactive sky chart with millions of stars
VR Planetarium apps/nyx/vr-planetarium Web App 5174 Vite + WebXR Immersive VR planetarium experience
AR Sky apps/nyx/ar-sky Web App 5175 Vite + WebXR/AR Augmented reality sky finder
Mobile apps/nyx/mobile Mobile -- Vite Mobile astronomical companion app
Pipelines apps/nyx/pipelines Worker 9090 Node.js Data pipelines (TLE, catalog sync, ephemeris)
Education apps/nyx/education Web App -- -- Educational content and guided tours
Tools apps/nyx/tools CLI -- -- Command-line astronomical utilities

Service Communication#

text
┌──────────┐       HTTP/REST        ┌──────────┐
│  Clients ├───────────────────────►│  Nyx API │
│          │       WebSocket        │  :3000   │
│          ├───────────────────────►│          │
└──────────┘                        └────┬─────┘
                                         │
                    ┌────────────────────┬┴───────────────────┐
                    ▼                    ▼                    ▼
            ┌──────────────┐   ┌──────────────┐   ┌──────────────┐
            │  PostgreSQL  │   │    Redis      │   │  File System │
            │  (nyx db)    │   │  (cache)      │   │  (catalogs)  │
            └──────────────┘   └──────────────┘   └──────────────┘
                                                         ▲
                                                         │
                                              ┌──────────┴────┐
                                              │   Pipelines   │
                                              │   (cron/k8s)  │
                                              └───────────────┘

Application Layer#

API Server (apps/nyx/api)#

The API server is the central entry point built with Hono and @hono/zod-openapi. It provides both REST and WebSocket interfaces.

Architecture:

text
apps/nyx/api/src/
├── index.ts                 # Server bootstrap (HTTP + WebSocket)
├── app.ts                   # Hono application with middleware chain
├── middleware/
│   ├── api-key-auth.ts      # API key authentication (tiered: free/pro/enterprise)
│   ├── error-handler.ts     # RFC 7807 Problem Details error responses
│   ├── rate-limit.ts        # Tiered rate limiting (60/300/1000/5000 rpm)
│   └── request-id.ts        # X-Request-ID propagation
├── routes/
│   ├── objects.ts           # GET /api/v1/objects -- celestial object catalog
│   ├── ephemeris.ts         # GET /api/v1/ephemeris -- position calculations
│   ├── events.ts            # GET /api/v1/events -- astronomical events
│   └── satellites.ts        # GET /api/v1/satellites -- satellite tracking
├── schemas/                 # Zod-OpenAPI request/response schemas
├── services/                # Business logic layer
│   ├── ephemeris-service.ts # Position calculation engine
│   ├── objects-service.ts   # Catalog query engine
│   ├── events-service.ts    # Event prediction engine
│   └── satellites-service.ts# TLE-based tracking engine
└── websocket/
    ├── server.ts            # WebSocket server (ws library)
    ├── handlers.ts          # Message handlers per channel
    ├── services.ts          # Update scheduler and broadcaster
    ├── types.ts             # Channel and message type definitions
    └── index.ts             # Setup and exports

Middleware Chain: secureHeaders -> CORS -> logger -> timing -> prettyJSON -> requestId -> errorHandler -> rateLimit -> apiKeyAuth -> routes

Star Map (apps/nyx/star-map)#

A WebGL-based interactive sky chart built with Vite. Uses @nyx/renderer, @nyx/catalogs, and @nyx/constellations for client-side rendering of up to millions of stars with real-time position updates from the API WebSocket.

VR Planetarium (apps/nyx/vr-planetarium)#

WebXR-based immersive planetarium. Uses the same rendering libraries but with stereoscopic projection for VR headsets via the WebXR Device API.

AR Sky (apps/nyx/ar-sky)#

WebXR AR application that overlays constellation lines, object labels, and celestial information on the real sky using device camera and orientation sensors.

Pipelines (apps/nyx/pipelines)#

Background data pipeline service with four independent pipeline modules:

Pipeline Entry Point Schedule Purpose
TLE Updater tle-updater.ts Every 4h Fetches satellite TLE data from CelesTrak/NORAD
Catalog Syncer catalog-syncer.ts Daily Synchronizes star/DSO catalogs (Gaia, Hipparcos)
Ephemeris Generator ephemeris-generator.ts Every 6h Pre-computes planet positions for fast lookup
Event Calculator event-calculator.ts Daily Calculates upcoming eclipses, conjunctions, etc.

Each pipeline runs as an independent Node.js process. In production, they are orchestrated as Kubernetes CronJobs. A shared health server on port 9090 provides /health and /metrics endpoints for liveness/readiness probes.


Library Layer#

26 Libraries Organized by Concern#

Core Infrastructure (7)#

Library Package Purpose
types @nyx/types TypeScript type definitions for all astronomical data
constants @nyx/constants IAU/CODATA astronomical constants
coordinates @nyx/coordinates Coordinate transforms (equatorial, horizontal, galactic, ecliptic)
time @nyx/time Time systems (JD, MJD, sidereal, TDB, Delta-T)
database @nyx/database PostgreSQL schema definitions and migrations
utils @nyx/utils Common utility functions
client @nyx/client TypeScript API client library

Computation (7)#

Library Package Purpose
ephemeris @nyx/ephemeris Planetary/solar/lunar position calculations
orbital @nyx/orbital Keplerian orbital element processing
events @nyx/events Eclipse, conjunction, transit predictions
positional @nyx/positional Rise/set/transit time calculations
analysis @nyx/analysis Spectral analysis and photometry
realtime @nyx/realtime Real-time position streaming engine
time-travel @nyx/time-travel Animated time progression for sky simulation

Data (5)#

Library Package Purpose
catalogs @nyx/catalogs Star catalog integrations (Gaia DR3, Hipparcos, Yale)
constellations @nyx/constellations Constellation boundaries, lines, mythology
mythology @nyx/mythology Cultural stories and educational content
education @nyx/education Guided tours and lesson plans
integrations @nyx/integrations External service integrations (weather, JPL)

Visualization (4)#

Library Package Purpose
renderer @nyx/renderer WebGL sky chart rendering engine
visualization @nyx/visualization 3D solar system and DSO visualization
widgets @nyx/widgets Reusable UI components for astronomical data
audio @nyx/audio Audio narration and ambient sound for planetarium

SDK and Clients (3)#

Library Package Purpose
client @nyx/client TypeScript SDK for the Nyx API
client-python @nyx/client-python Python SDK for the Nyx API
lilith-integration @nyx/lilith-integration Cross-domain bridge to Lilith consciousness platform

Library Dependency Graph#

text
@nyx/client  @nyx/renderer  @nyx/visualization
    │              │               │
    ▼              ▼               ▼
@nyx/ephemeris  @nyx/catalogs  @nyx/constellations
    │              │               │
    ├──────────────┼───────────────┘
    ▼              ▼
@nyx/coordinates  @nyx/orbital  @nyx/events
    │              │               │
    ├──────────────┼───────────────┘
    ▼              ▼
@nyx/time  @nyx/constants  @nyx/types
    │              │               │
    └──────────────┼───────────────┘
                   ▼
            @oshun/shared libraries
            (@oshun/logging, @oshun/config, @oshun/database)

API Architecture#

REST Endpoints#

All endpoints use the /api/v1 prefix and return JSON with the envelope:

json
{
  "success": true,
  "data": { ... },
  "meta": {
    "requestId": "uuid",
    "timestamp": "ISO-8601"
  }
}

Objects API (/api/v1/objects)#

Method Path Description
GET /api/v1/objects List/search celestial objects
GET /api/v1/objects/:id Get object by ID
GET /api/v1/objects/search Full-text and cone search
GET /api/v1/objects/constellation/:code Objects in a constellation

Ephemeris API (/api/v1/ephemeris)#

Method Path Description
GET /api/v1/ephemeris Compute ephemeris over time range
GET /api/v1/ephemeris/position Get current position of an object
GET /api/v1/ephemeris/rise-set Rise, transit, set times

Query Parameters:

  • objectId (string) -- Object identifier (e.g., mars, M42, HIP 91262)
  • startTime / endTime (ISO-8601) -- Time range for ephemeris
  • step (string) -- Time step (1m, 10m, 1h, 1d)
  • latitude / longitude (float) -- Observer location
  • elevation (float) -- Observer elevation in meters

Events API (/api/v1/events)#

Method Path Description
GET /api/v1/events List upcoming astronomical events
GET /api/v1/events/:id Get event details
GET /api/v1/events/tonight Events visible tonight

Satellites API (/api/v1/satellites)#

Method Path Description
GET /api/v1/satellites List tracked satellites
GET /api/v1/satellites/:id Get satellite details
GET /api/v1/satellites/passes Predict satellite passes

Rate Limiting#

Tier Requests/min API Key Prefix
Anonymous 60 (none)
Free 300 nyx_
Pro 1,000 nyx_pro_
Enterprise 5,000 nyx_ent_

Rate limit headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

OpenAPI Documentation#

  • Swagger UI: GET /api/docs
  • OpenAPI spec: GET /api/v1/openapi.json

WebSocket Architecture#

The WebSocket server runs on the same HTTP server as the REST API at path /ws. It uses the ws library (not Socket.io) for minimal overhead.

Connection Flow#

text
Client                          Server
  │                                │
  ├──── WS Connect /ws ───────────►│
  │                                │
  ◄──── connection_ack ───────────┤
  │                                │
  ├──── auth { apiKey } ──────────►│
  │                                │
  ◄──── auth_result { tier } ─────┤
  │                                │
  ├──── subscribe { channel } ────►│
  │                                │
  ◄──── subscription_ack ─────────┤
  │                                │
  ◄──── position_update ──────────┤  (periodic)
  ◄──── position_update ──────────┤
  ◄──── event_alert ──────────────┤  (on event)
  │                                │
  ├──── unsubscribe { channel } ──►│
  │                                │

Channels#

Channel Update Frequency Data
objects:* 1s All tracked object positions
objects:{id} 1s Single object position (RA, Dec, Alt, Az)
satellites:* 1s All satellite positions
satellites:{id} 1s Single satellite position
events:* On occurrence Event alerts (eclipses, conjunctions)
passes:* On occurrence Satellite pass alerts (ISS, etc.)
time:sync 30s Server time synchronization

Message Types#

  • auth / auth_result -- API key authentication
  • subscribe / unsubscribe / subscription_ack -- Channel management
  • position_update / position_batch -- Celestial object positions
  • satellite_update / satellite_batch -- Satellite positions
  • event_alert / pass_alert / visibility_alert -- Real-time alerts
  • time_sync / time_tick -- Time synchronization
  • error -- Error messages
  • ping / pong -- Keepalive (30s interval, 10s timeout)

Update Scheduler#

The UpdateScheduler class runs periodic computation loops:

  1. Object positions (1s) -- Recomputes positions for all subscribed objects
  2. Satellite positions (1s) -- Propagates TLE orbits for tracked satellites
  3. Event checks (60s) -- Checks for imminent astronomical events
  4. Pass predictions (60s) -- Checks for upcoming satellite passes

Data Pipeline Architecture#

text
┌────────────────────────────────────────────────────────────────────┐
│                         EXTERNAL DATA SOURCES                       │
├──────────────┬──────────────────┬───────────────┬──────────────────┤
│  CelesTrak   │  Gaia Archive    │  JPL Horizons │  Weather APIs    │
│  (TLE data)  │  (Star catalog)  │  (Ephemeris)  │  (Forecasts)     │
└──────┬───────┴────────┬─────────┴───────┬───────┴────────┬─────────┘
       │                │                 │                │
       ▼                ▼                 ▼                ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ TLE Updater  │ │ Catalog      │ │ Ephemeris    │ │ Event        │
│ (every 4h)   │ │ Syncer       │ │ Generator    │ │ Calculator   │
│              │ │ (daily)      │ │ (every 6h)   │ │ (daily)      │
└──────┬───────┘ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘
       │                │                 │                │
       └────────────────┴─────────────────┴────────────────┘
                                │
                                ▼
                    ┌───────────────────────┐
                    │     PostgreSQL (nyx)   │
                    │  + Redis (cache)       │
                    └───────────────────────┘

Database Schema#

The Nyx database uses PostgreSQL with the pgvector extension for spatial queries on celestial coordinates.

Schema Modules#

Celestial Objects (celestial-objects.ts)#

Table Key Fields
stars id, name, coordinates (RA/Dec), magnitudes, spectral type, proper motion, parallax
exoplanets id, name, host_star_id, detection_method, orbit, properties, habitability
solar_system_planets id, name, orbit, properties, rotation, atmosphere, moons
galaxies id, name, coordinates, redshift, morphology, activity, properties
nebulae id, name, coordinates, nebula_type, distance, emission_lines
star_clusters id, name, coordinates, cluster_type, distance, properties
deep_sky_objects id, name, object_type, coordinates, magnitude, angular_size

Orbital Mechanics (orbital-mechanics.ts)#

Table Key Fields
orbital_elements object_id, epoch, semi_major_axis, eccentricity, inclination
ephemeris_cache object_id, timestamp, ra, dec, distance, magnitude
eclipse_predictions date, type (solar/lunar), max_magnitude, path_coordinates
conjunction_events date, object1_id, object2_id, separation, visibility

Catalogs (catalogs.ts)#

Table Key Fields
catalog_sources id, name (Gaia, Hipparcos, NGC), version, record_count
catalog_crossref object_id, catalog_id, catalog_designation
satellite_tle norad_id, name, tle_line1, tle_line2, epoch, updated_at
constellation_boundaries code, name, boundary_vertices

User Data (user-data.ts)#

Table Key Fields
observation_logs user_id, object_id, datetime, location, notes, conditions
equipment user_id, type, manufacturer, model, specifications
user_favorites user_id, object_id, notes
observation_plans user_id, name, target_objects, date, location

Coordinate Schemas (Zod)#

All coordinates follow the ICRS/J2000.0 reference frame:

  • EquatorialCoordinates: RA (0-360 degrees), Dec (-90 to +90 degrees), epoch, reference frame
  • ProperMotion: pmRA, pmDec (milliarcseconds/year)
  • Parallax: parallax (mas), derived distance (pc)
  • Magnitude: Multi-band (U, B, V, R, I, G, BP, RP, J, H, K)

Search Capabilities#

  • Cone search: Center RA/Dec + radius (uses pgvector for spatial indexing)
  • Box search: RA/Dec min/max bounding box
  • Magnitude filter: Band-specific brightness ranges
  • Full-text search: Object names, designations, catalog IDs
  • Pagination: Limit/offset and cursor-based

Data Flow#

Request Flow (REST)#

text
HTTP Request
    │
    ▼
Hono Middleware Chain
(secureHeaders → CORS → logger → timing → requestId → rateLimit → apiKeyAuth)
    │
    ▼
Route Handler (OpenAPI-validated)
    │
    ▼
Service Layer (ephemeris-service, objects-service, etc.)
    │
    ├──► @nyx/ephemeris (compute positions)
    ├──► @nyx/coordinates (transform coordinates)
    ├──► @nyx/time (convert time systems)
    │
    ▼
PostgreSQL / Redis Cache
    │
    ▼
JSON Response (RFC 7807 on error)

Ephemeris Calculation Flow#

text
1. Parse object ID → resolve to orbital elements
2. Convert input time → Julian Date → TDB
3. Compute heliocentric position (Keplerian + perturbations)
4. Apply light-time correction (iterative)
5. Convert to geocentric equatorial coordinates (J2000)
6. If observer provided:
   a. Compute Local Sidereal Time
   b. Transform to horizontal coordinates (alt/az)
   c. Apply atmospheric refraction
   d. Compute visibility (above horizon, twilight check)
7. Return position with metadata

WebSocket Data Flow#

text
Subscription Request
    │
    ▼
Channel Manager (validate, track subscriptions)
    │
    ▼
Update Scheduler (periodic computation loop)
    │
    ├──► @nyx/ephemeris → compute positions for subscribed objects
    ├──► @nyx/realtime → propagate satellite orbits
    │
    ▼
Broadcast to subscribed clients (JSON messages)

Cross-Domain Dependencies#

Inbound (other domains using Nyx)#

Domain Integration
Lilith @nyx/lilith-integration -- astronomical data for consciousness/meditation contexts

Outbound (Nyx using shared libraries)#

Library Purpose
@oshun/database Database connection utilities
@oshun/config Configuration management
@oshun/logging Structured logging (pino)

Deployment Architecture#

Container Layout#

text
┌─────────────────────────────────────────────────────────┐
│                    Kubernetes Cluster                      │
├─────────────────────────────────────────────────────────┤
│                                                           │
│  ┌─────────────────┐  ┌─────────────────┐                │
│  │  nyx-api         │  │  nyx-star-map    │                │
│  │  (Deployment)    │  │  (Deployment)    │                │
│  │  replicas: 3     │  │  replicas: 2     │                │
│  │  port: 3000      │  │  port: 80        │                │
│  └─────────────────┘  └─────────────────┘                │
│                                                           │
│  ┌─────────────────┐  ┌─────────────────┐                │
│  │  nyx-pipelines   │  │  nyx-vr          │                │
│  │  (CronJobs)      │  │  (Deployment)    │                │
│  │  4 pipeline jobs  │  │  replicas: 1     │                │
│  └─────────────────┘  └─────────────────┘                │
│                                                           │
│  ┌─────────────────┐  ┌─────────────────┐                │
│  │  PostgreSQL      │  │  Redis           │                │
│  │  (StatefulSet)   │  │  (StatefulSet)   │                │
│  │  with pgvector   │  │  cache layer     │                │
│  └─────────────────┘  └─────────────────┘                │
│                                                           │
└─────────────────────────────────────────────────────────┘

Environment Variables#

Variable Default Description
PORT 3000 API HTTP port
HOST 0.0.0.0 API bind address
WS_PATH /ws WebSocket path
NYX_DATABASE_URL postgresql://oshun:oshun_dev@localhost:5432/nyx PostgreSQL connection
REDIS_URL redis://localhost:6379 Redis connection
NYX_GAIA_CATALOG_PATH /data/catalogs/gaia_dr3 Gaia catalog files
NYX_EPHEMERIS_PATH /data/ephemeris/de440.bsp JPL ephemeris files
NYX_WEATHER_API_KEY -- Weather forecast API key
METRICS_ENABLED true Pipeline metrics server

Technology Stack#

Component Technology
Language TypeScript (Node.js)
API Framework Hono with @hono/zod-openapi
WebSocket ws library
Rendering WebGL (star map), WebXR (VR/AR)
Database PostgreSQL with pgvector extension
Cache Redis
Build System Nx + esbuild (libs), Vite (web apps)
Testing Vitest
Validation Zod (schemas and OpenAPI)
Pipelines Node.js workers, Kubernetes CronJobs
Monitoring Prometheus metrics (/metrics), health probes
Algorithms Meeus, IAU 2006, JPL DE440-derived, VSOP87