# Nyx Domain

> Cosmic Observatory Platform Libraries

Nyx is the comprehensive astronomy and space exploration domain within the Oshun
monorepo. It provides all the building blocks needed to build a full-featured
cosmic observatory platform, including celestial object databases, orbital
mechanics calculations, sky visualization, ephemeris computation, and telescope
control integration.

## Table of Contents

1. [Architecture Overview](#architecture-overview)
2. [Library Categories](#library-categories)
3. [Getting Started](#getting-started)
4. [Core Libraries](#core-libraries)
5. [Celestial Data](#celestial-data)
6. [Orbital Mechanics](#orbital-mechanics)
7. [Visualization](#visualization)
8. [Telescope Control](#telescope-control)
9. [User Features](#user-features)
10. [Configuration](#configuration)
11. [Testing](#testing)

---

## Architecture Overview

The Nyx domain follows a modular architecture where each library handles a
specific astronomical concern. Libraries are designed to be composable and can
be used independently or together.

```
┌──────────────────────────────────────────────────────────────────────────┐
│                           APPLICATION LAYER                               │
│  (Web/Mobile apps, planetarium software, observation planning tools)     │
└─────────────────────────────────┬────────────────────────────────────────┘
                                  │
┌─────────────────────────────────▼────────────────────────────────────────┐
│                             NYX SDK                                       │
│  @nyx/sdk - Unified entry point for all cosmic observatory features      │
└─────────────────────────────────┬────────────────────────────────────────┘
                                  │
        ┌─────────────────────────┼─────────────────────────────────────┐
        │                         │                                     │
        ▼                         ▼                                     ▼
┌───────────────┐    ┌────────────────────┐    ┌────────────────────────┐
│  CELESTIAL    │    │   ORBITAL          │    │    VISUALIZATION       │
│  DATA         │    │   MECHANICS        │    │                        │
├───────────────┤    ├────────────────────┤    ├────────────────────────┤
│ star-catalogs │    │ ephemeris          │    │ sky-renderer           │
│ planet-data   │    │ orbital-elements   │    │ constellation-renderer │
│ galaxy-data   │    │ eclipse-predictor  │    │ object-annotations     │
│ dso-catalogs  │    │ conjunction-finder │    │ 3d-visualization       │
│ asteroid-data │    │ transit-calculator │    │ vr-planetarium         │
└───────────────┘    └────────────────────┘    └────────────────────────┘
        │                         │                                     │
        └─────────────────────────┼─────────────────────────────────────┘
                                  │
        ┌─────────────────────────┼─────────────────────────────────────┐
        │                         │                                     │
        ▼                         ▼                                     ▼
┌───────────────┐    ┌────────────────────┐    ┌────────────────────────┐
│  TELESCOPE    │    │   USER             │    │    OBSERVATION         │
│  CONTROL      │    │   FEATURES         │    │    PLANNING            │
├───────────────┤    ├────────────────────┤    ├────────────────────────┤
│ ascom         │    │ observation-log    │    │ visibility-calculator  │
│ indi          │    │ equipment-manager  │    │ session-planner        │
│ goto-control  │    │ imaging-workflow   │    │ weather-integration    │
│ autoguider    │    │ gamification       │    │ light-pollution        │
│ plate-solver  │    │ social-features    │    │ rise-set-times         │
└───────────────┘    └────────────────────┘    └────────────────────────┘
                                  │
                                  ▼
        ┌────────────────────────────────────────────────────┐
        │                   CORE LAYER                        │
        ├────────────────────────────────────────────────────┤
        │ @nyx/core - Types, validation, utilities           │
        │ @nyx/database - Celestial object storage           │
        │ @nyx/coordinates - Coordinate transformations      │
        │ @nyx/time - Time systems (UTC, JD, TDB, sidereal)  │
        │ @nyx/constants - Astronomical constants            │
        └────────────────────────────────────────────────────┘
                                  │
                                  ▼
        ┌────────────────────────────────────────────────────┐
        │              OSHUN SHARED LIBRARIES                 │
        │ @oshun/logging, @oshun/config, @oshun/database...  │
        └────────────────────────────────────────────────────┘
```

---

## Library Categories

### Core Infrastructure (7 libraries)

| Library       | Description                                        |
| ------------- | -------------------------------------------------- |
| `core`        | Base types, validation, and utilities              |
| `database`    | Celestial object database abstractions             |
| `coordinates` | Coordinate systems and transformations             |
| `time`        | Time systems (Julian dates, sidereal time, epochs) |
| `constants`   | Astronomical constants and physical values         |
| `utils`       | Common utility functions                           |
| `types`       | TypeScript type definitions                        |

### Celestial Data (8 libraries)

| Library         | Description                             |
| --------------- | --------------------------------------- |
| `star-catalogs` | Star catalog integrations (Gaia, Tycho) |
| `planet-data`   | Solar system and exoplanet data         |
| `galaxy-data`   | Galaxy catalogs and properties          |
| `dso-catalogs`  | Deep sky object catalogs (NGC, Messier) |
| `asteroid-data` | Asteroid and comet databases            |
| `satellite-tle` | Artificial satellite TLE tracking       |
| `meteor-data`   | Meteor shower predictions               |
| `variable-star` | Variable star monitoring                |

### Orbital Mechanics (6 libraries)

| Library             | Description                          |
| ------------------- | ------------------------------------ |
| `ephemeris`         | High-precision position calculations |
| `orbital-elements`  | Keplerian orbital element handling   |
| `eclipse-predictor` | Solar and lunar eclipse predictions  |
| `conjunction`       | Planetary conjunction finder         |
| `transit`           | Planetary transit calculations       |
| `perturbations`     | Gravitational perturbation modeling  |

### Visualization (7 libraries)

| Library             | Description                              |
| ------------------- | ---------------------------------------- |
| `sky-renderer`      | 2D sky chart rendering                   |
| `3d-visualization`  | 3D solar system visualization            |
| `constellation`     | Constellation rendering and boundaries   |
| `object-annotation` | Object labeling and information overlays |
| `vr-planetarium`    | VR planetarium experience                |
| `ar-starfinder`     | AR-based object identification           |
| `timeline`          | Time-based animation and playback        |

### Telescope Control (6 libraries)

| Library       | Description                  |
| ------------- | ---------------------------- |
| `ascom`       | ASCOM telescope protocol     |
| `indi`        | INDI protocol implementation |
| `goto`        | GoTo mount control           |
| `autoguider`  | Autoguiding interface        |
| `plate-solve` | Astrometric plate solving    |
| `camera`      | Astronomical camera control  |

### Observation Planning (5 libraries)

| Library      | Description                          |
| ------------ | ------------------------------------ |
| `visibility` | Object visibility calculations       |
| `planner`    | Observation session planning         |
| `weather`    | Weather forecast integration         |
| `light-poll` | Light pollution mapping              |
| `rise-set`   | Rise, transit, set time calculations |

### User Features (5 libraries)

| Library           | Description                      |
| ----------------- | -------------------------------- |
| `observation-log` | Personal observation logging     |
| `equipment`       | Equipment inventory management   |
| `imaging`         | Astrophotography workflow        |
| `gamification`    | Achievement and challenge system |
| `social`          | Community features and sharing   |

---

## Getting Started

### Installation

```bash
# Install the Nyx SDK (includes all essential features)
pnpm add @nyx/sdk

# Or install individual libraries
pnpm add @nyx/core @nyx/ephemeris @nyx/sky-renderer
```

### Basic Usage

```typescript
import { Nyx } from '@nyx/sdk';
import { Observer, CelestialCoordinates } from '@nyx/core';
import { calculatePosition } from '@nyx/ephemeris';

// Create an observer location
const observer: Observer = {
  latitude: 40.7128, // New York City
  longitude: -74.006,
  elevation: 10, // meters
  timezone: 'America/New_York',
};

// Get current position of Mars
const marsPosition = await calculatePosition('mars', new Date(), observer);

console.log(`Mars is at RA: ${marsPosition.ra}, Dec: ${marsPosition.dec}`);
console.log(
  `Altitude: ${marsPosition.altitude}°, Azimuth: ${marsPosition.azimuth}°`
);
```

### Render a Star Chart

```typescript
import { SkyRenderer } from '@nyx/sky-renderer';
import { StarCatalog } from '@nyx/star-catalogs';

const renderer = new SkyRenderer({
  width: 1920,
  height: 1080,
  projection: 'stereographic',
  limitingMagnitude: 6.5,
});

// Load star catalog
const stars = await StarCatalog.loadBrightStars();

// Render the current sky
const canvas = renderer.render({
  observer,
  datetime: new Date(),
  stars,
  showConstellations: true,
  showGrid: true,
});
```

### Calculate Eclipse

```typescript
import { EclipsePredictor } from '@nyx/eclipse-predictor';

const predictor = new EclipsePredictor();

// Find next solar eclipse visible from observer
const nextEclipse = await predictor.findNextSolarEclipse({
  observer,
  after: new Date(),
  type: 'any', // 'total', 'partial', 'annular', 'any'
});

console.log(`Next eclipse: ${nextEclipse.date}`);
console.log(`Type: ${nextEclipse.type}`);
console.log(`Maximum magnitude: ${nextEclipse.magnitude}`);
```

---

## Core Libraries

### @nyx/core

The foundation library providing base types and utilities.

```typescript
import {
  Observer,
  CelestialCoordinates,
  HorizontalCoordinates,
  EquatorialCoordinates,
  GalacticCoordinates,
  EclipticCoordinates,
  CelestialObject,
  Star,
  Planet,
  DeepSkyObject,
} from '@nyx/core';
```

### @nyx/coordinates

Coordinate system transformations.

```typescript
import {
  equatorialToHorizontal,
  horizontalToEquatorial,
  equatorialToGalactic,
  equatorialToEcliptic,
  precessCoordinates,
  aberrationCorrection,
  refractedAltitude,
} from '@nyx/coordinates';

// Convert RA/Dec to Alt/Az
const horizontal = equatorialToHorizontal(
  { ra: 83.822, dec: -5.391 }, // Orion Nebula
  observer,
  new Date()
);
```

### @nyx/time

Astronomical time systems.

```typescript
import {
  toJulianDate,
  fromJulianDate,
  getModifiedJulianDate,
  getLocalSiderealTime,
  getGreenwichSiderealTime,
  deltaT,
  tdbToTt,
  besselianYear,
} from '@nyx/time';

const jd = toJulianDate(new Date());
const lst = getLocalSiderealTime(jd, observer.longitude);
```

### @nyx/constants

Astronomical constants.

```typescript
import {
  AU, // Astronomical Unit in km
  LIGHT_YEAR, // Light year in km
  PARSEC, // Parsec in km
  SPEED_OF_LIGHT, // Speed of light in km/s
  GRAVITATIONAL_CONST, // Gravitational constant
  SOLAR_MASS, // Solar mass in kg
  EARTH_RADIUS, // Earth equatorial radius
  OBLIQUITY_J2000, // Earth's obliquity at J2000
  J2000, // J2000 epoch as Julian Date
} from '@nyx/constants';
```

---

## Celestial Data

### @nyx/star-catalogs

Comprehensive star catalog access.

```typescript
import {
  StarCatalog,
  GaiaQuery,
  HipparcosCatalog,
  YaleBrightStarCatalog,
} from '@nyx/star-catalogs';

// Query nearby stars from Gaia DR3
const nearbyStars = await GaiaQuery.findNearbyStars({
  centerRa: 100,
  centerDec: 20,
  radius: 5, // degrees
  maxMagnitude: 10,
  limit: 1000,
});

// Get a specific star by catalog ID
const vega = await StarCatalog.getByHip(91262);
console.log(vega.name); // "Vega"
console.log(vega.magnitude); // 0.03
console.log(vega.spectralType); // "A0V"
```

### @nyx/planet-data

Solar system and exoplanet information.

```typescript
import {
  SolarSystemPlanet,
  ExoplanetCatalog,
  PlanetaryMoon,
} from '@nyx/planet-data';

// Get Jupiter data
const jupiter = SolarSystemPlanet.get('jupiter');
console.log(jupiter.mass); // In Earth masses
console.log(jupiter.orbitalPeriod); // In days
console.log(jupiter.moons); // Array of moons

// Query exoplanets
const habitableZone = await ExoplanetCatalog.findInHabitableZone({
  minRadius: 0.5, // Earth radii
  maxRadius: 2.0,
});
```

---

## Telescope Control

### @nyx/ascom

ASCOM Alpaca protocol for telescope control.

```typescript
import { AscomTelescope, AscomCamera } from '@nyx/ascom';

// Connect to telescope
const telescope = new AscomTelescope({
  host: '192.168.1.100',
  port: 11111,
  deviceNumber: 0,
});

await telescope.connect();

// Slew to target
await telescope.slewToCoordinatesAsync({
  ra: 5.5334, // hours
  dec: -5.391, // degrees
});

// Get current position
const position = await telescope.getPosition();
console.log(`Pointing at RA: ${position.ra}h, Dec: ${position.dec}°`);
```

---

## Configuration

### Environment Variables

```bash
# Database
NYX_DATABASE_URL=postgresql://user:pass@localhost:5432/nyx

# Star catalog paths
NYX_GAIA_CATALOG_PATH=/data/catalogs/gaia_dr3
NYX_HIPPARCOS_PATH=/data/catalogs/hipparcos

# Ephemeris data
NYX_EPHEMERIS_PATH=/data/ephemeris/de440.bsp

# External APIs
NYX_WEATHER_API_KEY=your_api_key
NYX_LIGHT_POLLUTION_API=https://api.lightpollutionmap.info

# Telescope
NYX_ASCOM_HOST=localhost
NYX_ASCOM_PORT=11111
```

---

## Testing

All Nyx libraries include comprehensive test suites.

```bash
# Run all Nyx tests
pnpm nx run-many -t test --projects=tag:scope:nyx

# Run specific library tests
pnpm nx test nyx-ephemeris
pnpm nx test nyx-coordinates

# Run with coverage
pnpm nx test nyx-core --coverage
```

### Test Utilities

```typescript
import {
  createMockObserver,
  createMockStar,
  createMockPlanet,
  KNOWN_POSITIONS, // Verified celestial positions for testing
} from '@nyx/testing';

describe('Ephemeris', () => {
  it('should calculate Mars position within tolerance', async () => {
    const observer = createMockObserver();
    const position = await calculatePosition('mars', KNOWN_POSITIONS.mars.date);

    expect(position.ra).toBeCloseTo(KNOWN_POSITIONS.mars.ra, 4);
    expect(position.dec).toBeCloseTo(KNOWN_POSITIONS.mars.dec, 4);
  });
});
```

---

## Related Documentation

- [Astronomical Algorithms](docs/algorithms.md)
- [Coordinate Systems](docs/coordinates.md)
- [Time Systems](docs/time.md)
- [Catalog Formats](docs/catalogs.md)
- [Telescope Protocols](docs/telescope-protocols.md)
