# Nyx Architecture

> **Canonical source:** the canonical architecture document for this domain is
> [`deep-dive/architecture.md`](./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](#system-overview)
2. [Service Architecture](#service-architecture)
3. [Application Layer](#application-layer)
4. [Library Layer](#library-layer)
5. [API Architecture](#api-architecture)
6. [WebSocket Architecture](#websocket-architecture)
7. [Data Pipeline Architecture](#data-pipeline-architecture)
8. [Database Schema](#database-schema)
9. [Data Flow](#data-flow)
10. [Cross-Domain Dependencies](#cross-domain-dependencies)
11. [Deployment Architecture](#deployment-architecture)
12. [Technology Stack](#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.

```
                         ┌────────────────────────────────┐
                         │         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

```
┌──────────┐       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:**

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

```
@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

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

```
┌────────────────────────────────────────────────────────────────────┐
│                         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)

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

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

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

```
┌─────────────────────────────────────────────────────────┐
│                    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     |
