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#
System Overview
Service Architecture
Application Layer
Library Layer
API Architecture
WebSocket Architecture
Data Pipeline Architecture
Database Schema
Data Flow
Cross-Domain Dependencies
Deployment Architecture
Technology Stack
System Overview#
Nyx is a full-stack astronomical education and observation platform. The
architecture is designed around three core principles:
Computational accuracy -- Ephemeris, coordinate transforms, and time
systems are implemented from peer-reviewed astronomical algorithms (Meeus,
IAU standards, JPL-derived elements).
Real-time delivery -- WebSocket channels push position updates, satellite
passes, and event alerts at configurable intervals.
Modular library composition -- 26 libraries provide independent
capabilities that compose into 8 applications.
text Copy
┌────────────────────────────────┐
│ 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 Copy
┌──────────┐ 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 Copy
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 Copy
@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 Copy
{
"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 Copy
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:
Object positions (1s) -- Recomputes positions for all subscribed objects
Satellite positions (1s) -- Propagates TLE orbits for tracked satellites
Event checks (60s) -- Checks for imminent astronomical events
Pass predictions (60s) -- Checks for upcoming satellite passes
Data Pipeline Architecture#
text Copy
┌────────────────────────────────────────────────────────────────────┐
│ 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 Copy
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 Copy
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 Copy
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 Copy
┌─────────────────────────────────────────────────────────┐
│ 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