# Nyx Cosmic Observatory - Microservices Architecture

## Overview

Nyx Cosmic Observatory is a comprehensive astronomical platform providing
real-time sky visualization, celestial object exploration, educational content,
and observation tracking. The platform is built as a distributed microservices
architecture following the established Oshun patterns.

## Architecture Principles

### 1. Event-Driven Communication

- Services communicate primarily through Redis-based event bus
- HTTP/REST used for synchronous queries and state retrieval
- All events follow the `EventEnvelope` schema from `@oshun/contracts`

### 2. Domain Isolation

- Each service owns its data and schema
- No direct database access between services
- Data sharing through events and API contracts

### 3. Eventual Consistency

- Celestial calculations are cached and updated periodically
- Real-time data propagated via events
- Stale-while-revalidate pattern for expensive computations

### 4. Horizontal Scalability

- Stateless services with shared Redis/PostgreSQL
- Service discovery for load balancing
- CDN for static astronomical data

---

## Service Architecture

```
                                   ┌─────────────────────────────────────────────────────────────────┐
                                   │                         API Gateway                              │
                                   │                    (Traefik / @oshun/traefik-config)                    │
                                   └────────────┬────────────┬────────────┬────────────┬─────────────┘
                                                │            │            │            │
                           ┌────────────────────┼────────────┼────────────┼────────────┼────────────────────┐
                           │                    │            │            │            │                    │
                           ▼                    ▼            ▼            ▼            ▼                    │
              ┌─────────────────────┐ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐          │
              │  nyx-catalog-service│ │nyx-compute-svc  │ │ nyx-render-svc  │ │nyx-realtime-svc │          │
              │                     │ │                 │ │                 │ │                 │          │
              │ • Star/DSO queries  │ │ • Ephemeris     │ │ • Tile gen      │ │ • WebSocket     │          │
              │ • Catalog CRUD      │ │ • Position calc │ │ • Star fields   │ │ • Live tracking │          │
              │ • Search/filter     │ │ • Rise/set times│ │ • Overlays      │ │ • Event stream  │          │
              │ • User observations │ │ • Event predict │ │ • Export        │ │ • Notifications │          │
              └──────────┬──────────┘ └────────┬────────┘ └────────┬────────┘ └────────┬────────┘          │
                         │                     │                   │                   │                    │
                         └──────────┬──────────┴───────────────────┴───────────────────┘                    │
                                    │                                                                        │
                                    ▼                                                                        │
              ┌─────────────────────────────────────────────────────────────────────────────────────────────┤
              │                                    Event Bus (Redis)                                         │
              │                                   @oshun/event-bus                                           │
              └─────────────────────────────────────────────────────────────────────────────────────────────┘
                                    │
                    ┌───────────────┼───────────────┬───────────────┬───────────────┐
                    │               │               │               │               │
                    ▼               ▼               ▼               ▼               ▼
              ┌───────────┐  ┌───────────┐  ┌───────────┐  ┌───────────┐  ┌───────────┐
              │PostgreSQL │  │   Redis   │  │   MinIO   │  │ External  │  │    CDN    │
              │ (nyx_db)  │  │  (Cache)  │  │ (Storage) │  │   APIs    │  │  (Tiles)  │
              └───────────┘  └───────────┘  └───────────┘  └───────────┘  └───────────┘
```

---

## Service Definitions

### 1. nyx-catalog-service

**Purpose**: Primary data access layer for astronomical objects, user data, and
catalog management.

**Responsibilities**:

- Query celestial objects (stars, planets, galaxies, nebulae, clusters)
- Manage catalog cross-references (Hipparcos, Gaia, Messier, NGC, etc.)
- Handle user observations, saved views, and annotations
- Provide search and filtering across catalogs
- Manage observing lists and programs
- Track tour progress and achievements

**API Endpoints**:

```
# Celestial Object Queries
GET  /v1/objects                       # Search objects with filters
GET  /v1/objects/:id                   # Get object by ID
GET  /v1/objects/by-catalog/:type/:id  # Get by catalog ID (e.g., /by-catalog/messier/31)
GET  /v1/objects/cone-search           # Spatial cone search (RA, Dec, radius)
GET  /v1/objects/region                # Objects in sky region

# Stars
GET  /v1/stars                         # Query stars with filters
GET  /v1/stars/:id                     # Get star details
GET  /v1/stars/:id/exoplanets          # Get star's exoplanets

# Deep Sky Objects
GET  /v1/deep-sky                      # Query DSOs
GET  /v1/deep-sky/:type                # Filter by type (galaxy, nebula, cluster)

# Solar System
GET  /v1/solar-system/planets          # Get planets
GET  /v1/solar-system/moons/:planetId  # Get moons of planet
GET  /v1/solar-system/asteroids        # Query asteroids
GET  /v1/solar-system/comets           # Query comets

# Satellites
GET  /v1/satellites                    # Query artificial satellites
GET  /v1/satellites/:noradId           # Get by NORAD ID

# User Data
GET  /v1/users/:userId/observations    # User's observation logs
POST /v1/users/:userId/observations    # Log new observation
GET  /v1/users/:userId/saved-views     # User's saved views
POST /v1/users/:userId/saved-views     # Save a view
GET  /v1/users/:userId/observing-lists # User's observing lists
GET  /v1/users/:userId/achievements    # User's achievements
GET  /v1/users/:userId/statistics      # User statistics

# Catalog Management
GET  /v1/catalogs                      # List available catalogs
GET  /v1/catalogs/:type/metadata       # Get catalog metadata
GET  /v1/constellations                # List constellations
GET  /v1/constellations/:abbr          # Get constellation details

# Tours
GET  /v1/tours                         # List educational tours
GET  /v1/tours/:tourId                 # Get tour details
GET  /v1/tours/:tourId/stops           # Get tour stops
```

**Events Published**:

```typescript
nyx.object.viewed; // User viewed an object
nyx.observation.logged; // User logged observation
nyx.observation.updated; // Observation updated
nyx.view.saved; // User saved a view
nyx.list.created; // Observing list created
nyx.list.item.observed; // Item marked observed
nyx.achievement.unlocked; // User earned achievement
nyx.tour.started; // User started tour
nyx.tour.completed; // User completed tour
```

**Events Consumed**:

```typescript
nyx.compute.ephemeris.updated; // Update cached positions
nyx.realtime.satellite.updated; // Update satellite TLE
```

**Database Tables**:

- `celestial_objects`, `stars`, `exoplanets`, `galaxies`, `nebulae`,
  `star_clusters`
- `solar_system_objects`, `artificial_satellites`
- `catalog_cross_references`, `name_aliases`, `constellations`
- `observation_logs`, `saved_views`, `custom_annotations`
- `observing_lists`, `observing_list_items`
- `tour_definitions`, `tour_stops`, `tour_progress`
- `achievement_definitions`, `user_achievements`, `user_statistics`
- `user_preferences`

**Technology Stack**:

- Fastify HTTP server
- PostgreSQL with PostGIS
- Redis for caching frequent queries
- pg_trgm for fuzzy name search

---

### 2. nyx-compute-service

**Purpose**: Astronomical calculations engine for positions, ephemerides, and
predictions.

**Responsibilities**:

- Calculate ephemeris for celestial objects
- Compute rise/transit/set times for observer locations
- Predict celestial events (conjunctions, eclipses, transits)
- Calculate satellite passes and visibility
- Perform coordinate transformations
- Solve orbital mechanics (Keplerian propagation, TLE)

**API Endpoints**:

```
# Ephemeris
GET  /v1/ephemeris/:objectId                  # Get current position
POST /v1/ephemeris/batch                      # Batch position calculation
GET  /v1/ephemeris/:objectId/range            # Positions over time range

# Observer-Specific Calculations
GET  /v1/observer/rise-transit-set            # Rise/transit/set times
GET  /v1/observer/altitude-azimuth            # Alt/az for object
GET  /v1/observer/visible-objects             # Objects visible now
GET  /v1/observer/tonight                     # Tonight's observing plan

# Solar System Dynamics
GET  /v1/planets/:planetId/position           # Planet position
GET  /v1/planets/positions                    # All planet positions
GET  /v1/moon/phase                           # Current lunar phase
GET  /v1/moon/phases                          # Lunar phases for period

# Satellite Tracking
GET  /v1/satellites/:noradId/position         # Current satellite position
GET  /v1/satellites/:noradId/passes           # Visible passes for observer
POST /v1/satellites/propagate                 # Propagate TLE

# Events & Predictions
GET  /v1/events/upcoming                      # Upcoming celestial events
GET  /v1/events/eclipses                      # Eclipse predictions
GET  /v1/events/conjunctions                  # Planetary conjunctions
GET  /v1/events/meteor-showers                # Meteor shower forecasts
GET  /v1/events/transits                      # Transit predictions

# Coordinate Transformations
POST /v1/coordinates/transform                # Transform between systems
POST /v1/coordinates/precess                  # Precession calculation

# Time Calculations
GET  /v1/time/sidereal                        # Local sidereal time
GET  /v1/time/julian                          # Julian date conversion
```

**Events Published**:

```typescript
nyx.compute.ephemeris.updated; // Batch ephemeris update completed
nyx.compute.event.predicted; // New event prediction available
nyx.compute.eclipse.upcoming; // Eclipse prediction
nyx.compute.conjunction.upcoming; // Conjunction prediction
nyx.compute.satellite.pass; // Satellite pass prediction
```

**Events Consumed**:

```typescript
nyx.catalog.tle.updated; // New TLE data available
nyx.catalog.orbital.updated; // Orbital elements updated
nyx.realtime.time.sync; // Time synchronization
```

**Computation Modules**:

```typescript
// Core computation modules
ephemeris/
├── planets.ts          // Planetary position algorithms (VSOP87)
├── moon.ts             // Lunar position (ELP2000)
├── stars.ts            // Stellar position with proper motion
├── comets.ts           // Comet positions (orbital elements)
├── asteroids.ts        // Minor planet positions

orbital/
├── kepler.ts           // Keplerian propagation
├── sgp4.ts             // SGP4/SDP4 for satellites
├── perturbations.ts    // N-body perturbations

observer/
├── horizontal.ts       // Alt/Az calculations
├── rise-set.ts         // Rise/transit/set computation
├── refraction.ts       // Atmospheric refraction
├── twilight.ts         // Twilight calculations

coordinates/
├── transforms.ts       // Coordinate transformations
├── precession.ts       // Precession/nutation
├── aberration.ts       // Aberration corrections

time/
├── julian.ts           // Julian date utilities
├── sidereal.ts         // Sidereal time
├── deltaT.ts           // Delta-T calculations
```

**Caching Strategy**:

- Redis cache for ephemeris data (1-hour TTL for planets, 24-hour for stars)
- Precomputed monthly event calendars
- Memoized expensive calculations (precession matrices)

**Technology Stack**:

- Fastify HTTP server
- Redis for computation cache
- Worker threads for parallel computation
- WASM modules for performance-critical algorithms (optional)

---

### 3. nyx-render-service

**Purpose**: Generate visual tiles, star field images, and export formats for
the sky map.

**Responsibilities**:

- Generate star field tiles for different zoom levels
- Render constellation lines and boundaries
- Create overlay tiles (Milky Way, ecliptic grid, etc.)
- Generate object markers and labels
- Export sky maps in various formats
- Create thumbnails and previews

**API Endpoints**:

```
# Tile Generation (TMS/XYZ format)
GET  /v1/tiles/stars/:z/:x/:y.png            # Star field tiles
GET  /v1/tiles/constellations/:z/:x/:y.png   # Constellation lines
GET  /v1/tiles/boundaries/:z/:x/:y.png       # Constellation boundaries
GET  /v1/tiles/grid/:type/:z/:x/:y.png       # Coordinate grids
GET  /v1/tiles/milkyway/:z/:x/:y.png         # Milky Way imagery
GET  /v1/tiles/dso/:z/:x/:y.png              # Deep sky object markers

# Custom Rendering
POST /v1/render/region                        # Render specific region
POST /v1/render/finder-chart                  # Generate finder chart
POST /v1/render/sky-view                      # Render sky view for time/location

# Annotations & Overlays
POST /v1/render/annotations                   # Render user annotations
POST /v1/render/markers                       # Custom object markers
POST /v1/render/trajectory                    # Object trajectory overlay

# Export
POST /v1/export/image                         # Export as PNG/JPEG/WEBP
POST /v1/export/pdf                           # Export as PDF
POST /v1/export/svg                           # Export as SVG

# Thumbnails
GET  /v1/thumbnails/object/:objectId          # Object thumbnail
GET  /v1/thumbnails/constellation/:abbr       # Constellation thumbnail
GET  /v1/thumbnails/tour/:tourId/stop/:stopId # Tour stop preview
```

**Tile Hierarchy**:

```
Zoom Levels:
├── Level 0-2:   Whole sky overview (stars to mag 4)
├── Level 3-5:   Wide field (stars to mag 6)
├── Level 6-8:   Medium field (stars to mag 9)
├── Level 9-11:  Narrow field (stars to mag 12)
├── Level 12-14: Close-up (stars to mag 15+, DSO details)
└── Level 15+:   Ultra close-up (individual object imagery)

Tile Specification:
├── Format: PNG with transparency (WebP for production)
├── Size: 256x256 or 512x512 pixels
├── Projection: Stereographic (configurable)
├── Color Schemes: Classic, Natural, Dark, High Contrast
```

**Events Published**:

```typescript
nyx.render.tile.generated; // Tile generation completed
nyx.render.export.ready; // Export file ready
nyx.render.cache.invalidated; // Tile cache cleared
```

**Events Consumed**:

```typescript
nyx.catalog.object.updated; // Re-render affected tiles
nyx.compute.ephemeris.updated; // Update planetary positions
nyx.user.annotation.created; // Prepare annotation render
```

**Rendering Pipeline**:

```typescript
pipeline/
├── projection/
│   ├── stereographic.ts        // Default sky projection
│   ├── mollweide.ts            // All-sky projection
│   ├── orthographic.ts         // Hemisphere view
│   └── gnomonic.ts             // Flat field projection

├── layers/
│   ├── stars.ts                // Star rendering
│   ├── dso.ts                  // Deep sky objects
│   ├── constellations.ts       // Lines and figures
│   ├── grid.ts                 // Coordinate grids
│   ├── milkyway.ts             // Milky Way background
│   └── annotations.ts          // User annotations

├── styling/
│   ├── themes.ts               // Color themes
│   ├── symbols.ts              // Object symbols
│   └── typography.ts           // Label rendering

└── output/
    ├── png.ts                  // PNG encoder
    ├── webp.ts                 // WebP encoder
    ├── svg.ts                  // Vector output
    └── pdf.ts                  // PDF generation
```

**Caching Strategy**:

- CDN for static tiles (permanent cache for fixed stars)
- Redis for recently generated custom tiles (1-hour TTL)
- S3/MinIO for exported files (24-hour TTL)
- Pre-generated tile sets for common views

**Technology Stack**:

- Fastify HTTP server
- Sharp/Canvas for image generation
- CDN (CloudFront/Cloudflare) for tile delivery
- MinIO for generated file storage
- Redis for tile metadata cache

---

### 4. nyx-realtime-service

**Purpose**: Real-time updates, live tracking, and push notifications.

**Responsibilities**:

- WebSocket connections for live updates
- Real-time satellite tracking
- ISS and bright satellite alerts
- Celestial event notifications
- Live meteor shower activity
- Aurora alerts (integration with space weather)
- User notification delivery

**API Endpoints**:

```
# WebSocket Connections
WS   /v1/ws/sky                               # Live sky updates
WS   /v1/ws/satellite/:noradId                # Track specific satellite
WS   /v1/ws/events                            # Live event stream
WS   /v1/ws/user/:userId                      # User notifications

# REST Endpoints
GET  /v1/live/satellites                      # Currently visible satellites
GET  /v1/live/iss                             # ISS current position & passes
GET  /v1/live/meteor-activity                 # Current meteor activity
GET  /v1/live/space-weather                   # Space weather conditions
GET  /v1/live/aurora                          # Aurora forecast

# Notifications
POST /v1/notifications/subscribe              # Subscribe to event types
POST /v1/notifications/unsubscribe            # Unsubscribe
GET  /v1/notifications/settings               # Get notification settings
PUT  /v1/notifications/settings               # Update settings

# Alerts
GET  /v1/alerts/upcoming                      # Upcoming alerts for user
POST /v1/alerts/create                        # Create custom alert
DELETE /v1/alerts/:alertId                    # Delete alert
```

**WebSocket Message Types**:

```typescript
// Sky updates (sent every 10 seconds)
{
  type: 'sky.update',
  timestamp: ISO8601,
  data: {
    siderealTime: number,
    planets: PlanetPosition[],
    moon: MoonData,
    sun: SunData
  }
}

// Satellite position (sent every second for tracked satellites)
{
  type: 'satellite.position',
  noradId: number,
  position: {
    latitude: number,
    longitude: number,
    altitude: number,
    velocity: number
  },
  visibility: {
    isVisible: boolean,
    magnitude: number,
    altitude: number,
    azimuth: number
  }
}

// Event alert
{
  type: 'event.alert',
  eventType: 'iss_pass' | 'meteor_peak' | 'eclipse_start' | ...,
  startsIn: number, // seconds until event
  data: EventData
}

// Notification
{
  type: 'notification',
  notificationType: 'achievement' | 'event' | 'social',
  payload: NotificationPayload
}
```

**Events Published**:

```typescript
nyx.realtime.satellite.visible; // Satellite becoming visible
nyx.realtime.iss.pass; // ISS pass alert
nyx.realtime.meteor.peak; // Meteor shower peak
nyx.realtime.aurora.alert; // Aurora visibility
nyx.realtime.event.imminent; // Celestial event starting soon
```

**Events Consumed**:

```typescript
nyx.compute.satellite.pass; // Pass predictions from compute
nyx.compute.event.predicted; // Event predictions
nyx.catalog.observation.logged; // User activity
nyx.achievement.unlocked; // Achievement notifications
```

**Data Sources**:

- CelesTrak (TLE updates every 2 hours)
- NOAA Space Weather Prediction Center
- IMO Meteor Network
- USGS Aurora Dashboard

**Technology Stack**:

- Fastify with @fastify/websocket
- Redis Pub/Sub for real-time distribution
- Bull queues for scheduled notifications
- External API integrations

---

## Cross-Service Communication

### Event Flow Diagram

```
                        ┌─────────────────────────────────────────────────────────────────┐
                        │                       Event Bus (Redis)                          │
                        │                                                                  │
┌──────────────┐        │  ┌─────────────────────────────────────────────────────────┐   │        ┌──────────────┐
│   Client     │        │  │                    Event Topics                          │   │        │   External   │
│  (Web/App)   │        │  │                                                          │   │        │    APIs      │
└──────┬───────┘        │  │  nyx.catalog.*     nyx.compute.*    nyx.realtime.*      │   │        └──────┬───────┘
       │                │  │  nyx.render.*      nyx.user.*       nyx.achievement.*   │   │               │
       │ HTTP/WS        │  └─────────────────────────────────────────────────────────┘   │               │
       │                │                           │                                      │               │
       ▼                │           ┌───────────────┼───────────────┐                     │               │
┌──────────────┐        │           │               │               │                     │               │
│ API Gateway  │◄───────┼───────────┤               │               ├─────────────────────┼───────────────┤
└──────┬───────┘        │           │               │               │                     │               │
       │                │           ▼               ▼               ▼                     │               │
       │         ┌──────┼─────────────────────────────────────────────────────────────────┼────────┐      │
       │         │      │                                                                  │        │      │
       ▼         ▼      │                                                                  │        ▼      ▼
┌─────────────────┐     │     ┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│ nyx-catalog     │◄────┼────►│ nyx-compute     │◄────┼────►│ nyx-render      │◄────┼────►│ nyx-realtime   │
│                 │     │     │                 │     │     │                 │     │     │                │
│ ┌─────────────┐ │     │     │ ┌─────────────┐ │     │     │ ┌─────────────┐ │     │     │ ┌────────────┐ │
│ │ PostgreSQL  │ │     │     │ │ Redis Cache │ │     │     │ │ CDN/S3      │ │     │     │ │ WebSocket  │ │
│ │ + PostGIS   │ │     │     │ │ + Workers   │ │     │     │ │ + Canvas    │ │     │     │ │ + Pub/Sub  │ │
│ └─────────────┘ │     │     │ └─────────────┘ │     │     │ └─────────────┘ │     │     │ └────────────┘ │
└─────────────────┘     │     └─────────────────┘     │     └─────────────────┘     │     └────────────────┘
                        │                             │                             │
                        └─────────────────────────────┴─────────────────────────────┘
```

### Service Dependencies

| Service              | Depends On                                                        | Provides To                |
| -------------------- | ----------------------------------------------------------------- | -------------------------- |
| nyx-catalog-service  | PostgreSQL, Redis                                                 | All services (data source) |
| nyx-compute-service  | nyx-catalog (object data), Redis                                  | nyx-render, nyx-realtime   |
| nyx-render-service   | nyx-catalog (objects), nyx-compute (positions), CDN               | Clients                    |
| nyx-realtime-service | nyx-compute (predictions), nyx-catalog (user data), External APIs | Clients                    |

### Request Flow Examples

**1. User Views Sky Map**

```
Client → API Gateway → nyx-render-service (tiles)
                    → nyx-catalog-service (object details on click)
                    → nyx-realtime-service (WebSocket for live updates)
```

**2. User Searches for Object**

```
Client → API Gateway → nyx-catalog-service (search)
       ← Object list with basic info
Client → API Gateway → nyx-compute-service (rise/set times for selected object)
       ← Rise/transit/set times
Client → API Gateway → nyx-render-service (finder chart)
       ← Finder chart image
```

**3. Satellite Tracking**

```
Client → nyx-realtime-service (WebSocket connect, track satellite X)
nyx-realtime-service → nyx-compute-service (initial position + pass prediction)
nyx-realtime-service → Client (position updates every second via WebSocket)
```

**4. User Logs Observation**

```
Client → API Gateway → nyx-catalog-service (POST observation)
nyx-catalog-service → Event Bus (nyx.observation.logged)
Event Bus → nyx-catalog-service (check achievements)
       → nyx-realtime-service (send notification if achievement unlocked)
```

---

## Data Flow

### Catalog Data Pipeline

```
External Sources          Processing                    Storage
┌─────────────┐          ┌──────────────┐           ┌──────────────┐
│ Gaia DR3    │          │              │           │              │
│ Hipparcos   │ ───ETL──►│ Data         │──────────►│ PostgreSQL   │
│ NGC/IC      │          │ Ingestion    │           │ + PostGIS    │
│ Messier     │          │ Pipeline     │           │              │
└─────────────┘          └──────────────┘           └──────────────┘
                                │
                                ▼
                         ┌──────────────┐           ┌──────────────┐
                         │ Index        │──────────►│ Search Index │
                         │ Builder      │           │ (pg_trgm)    │
                         └──────────────┘           └──────────────┘
```

### Real-time Data Pipeline

```
External Sources          Processing                    Delivery
┌─────────────┐          ┌──────────────┐           ┌──────────────┐
│ CelesTrak   │          │              │           │              │
│ (TLE)       │──Poll───►│ nyx-realtime │──Event───►│ Event Bus    │
│             │ (2hr)    │ TLE updater  │   Bus     │              │
└─────────────┘          └──────────────┘           └──────┬───────┘
                                                           │
┌─────────────┐          ┌──────────────┐                  │
│ Space       │          │              │                  ▼
│ Weather     │──Poll───►│ nyx-realtime │──WebSocket──►┌──────────────┐
│ APIs        │ (15min)  │ alert engine │              │   Clients    │
└─────────────┘          └──────────────┘              └──────────────┘
```

---

## Deployment Architecture

### Container Configuration

```yaml
services:
  nyx-catalog-service:
    replicas: 2
    resources:
      cpu: 500m
      memory: 512Mi
    env:
      - DATABASE_URL=postgresql://...
      - REDIS_URL=redis://...
    healthcheck: /health

  nyx-compute-service:
    replicas: 3 # CPU-intensive
    resources:
      cpu: 1000m
      memory: 1Gi
    env:
      - REDIS_URL=redis://...
      - WORKER_THREADS=4

  nyx-render-service:
    replicas: 2
    resources:
      cpu: 500m
      memory: 1Gi # Image processing
    env:
      - CDN_URL=https://...
      - S3_ENDPOINT=...

  nyx-realtime-service:
    replicas: 2
    resources:
      cpu: 250m
      memory: 256Mi
    env:
      - REDIS_URL=redis://...
      - CELESTRAK_API_KEY=...
```

### Network Configuration

```
External Traffic
       │
       ▼
┌──────────────┐     Internal Network
│   Traefik    │     ┌─────────────────────────────────────────┐
│   Gateway    │────►│                                         │
└──────────────┘     │  ┌─────────┐  ┌─────────┐  ┌─────────┐ │
       │             │  │catalog  │  │compute  │  │render   │ │
       │             │  │:8001    │  │:8002    │  │:8003    │ │
       │             │  └────┬────┘  └────┬────┘  └────┬────┘ │
       │             │       │            │            │      │
       ▼             │       └────────────┼────────────┘      │
┌──────────────┐     │                    │                   │
│   CDN        │     │  ┌─────────┐  ┌────┴────┐  ┌─────────┐│
│ (Cloudflare) │◄────┤  │realtime │  │  Redis  │  │Postgres ││
└──────────────┘     │  │:8004    │  │         │  │         ││
                     │  └─────────┘  └─────────┘  └─────────┘│
                     └─────────────────────────────────────────┘
```

---

## Security Considerations

### Authentication & Authorization

- JWT tokens from `@oshun/auth` for user authentication
- API keys for service-to-service communication
- Rate limiting per user/IP for expensive operations
- Read-only public access for basic queries

### Data Security

- PII (user data) encrypted at rest
- Observation logs contain location data (user consent required)
- External API keys stored in secrets manager

### Input Validation

- All inputs validated with Zod schemas
- Coordinate bounds checking
- Query complexity limits to prevent DoS

---

## Monitoring & Observability

### Metrics (Prometheus)

```typescript
// Catalog service
nyx_catalog_queries_total{object_type, query_type}
nyx_catalog_query_duration_seconds{object_type}
nyx_catalog_cache_hit_ratio

// Compute service
nyx_compute_ephemeris_calculations_total
nyx_compute_calculation_duration_seconds{calculation_type}
nyx_compute_worker_utilization

// Render service
nyx_render_tiles_generated_total{zoom_level, layer}
nyx_render_tile_generation_duration_seconds
nyx_render_cache_hit_ratio{layer}

// Realtime service
nyx_realtime_websocket_connections_active
nyx_realtime_messages_sent_total{message_type}
nyx_realtime_external_api_latency_seconds{api}
```

### Logging

- Structured JSON logs via `@oshun/logging`
- Correlation IDs for request tracing
- Error tracking with stack traces

### Tracing

- OpenTelemetry spans for all service calls
- Trace propagation across service boundaries
- Visualization in Jaeger/Grafana Tempo

---

## Future Considerations

### Planned Enhancements

1. **Machine Learning Integration**
   - Object classification from user images
   - Personalized observation recommendations
   - Weather prediction for observing conditions

2. **Social Features**
   - Shared observing sessions
   - Public observation logs
   - Community events and challenges

3. **Advanced Visualization**
   - 3D sky rendering
   - VR/AR support
   - Time-lapse animations

4. **Data Expansion**
   - Full Gaia DR3 integration (1.8B sources)
   - Real-time asteroid tracking
   - Space debris monitoring

---

## Appendix

### A. Technology Stack Summary

| Component         | Technology                             |
| ----------------- | -------------------------------------- |
| HTTP Framework    | Fastify                                |
| Database          | PostgreSQL + PostGIS                   |
| Cache             | Redis                                  |
| Message Bus       | Redis Pub/Sub                          |
| File Storage      | MinIO / S3                             |
| CDN               | Cloudflare / CloudFront                |
| Image Processing  | Sharp / Node Canvas                    |
| Container Runtime | Docker                                 |
| Service Discovery | Redis-based (@oshun/service-discovery) |
| API Gateway       | Traefik                                |
| Monitoring        | Prometheus + Grafana                   |
| Tracing           | OpenTelemetry + Jaeger                 |
| Logging           | Pino + Elasticsearch                   |

### B. External API Dependencies

| API                    | Purpose                 | Update Frequency |
| ---------------------- | ----------------------- | ---------------- |
| CelesTrak              | TLE data for satellites | 2 hours          |
| NOAA SWPC              | Space weather           | 15 minutes       |
| IMO                    | Meteor activity         | 1 hour           |
| JPL Horizons           | Ephemeris data          | On-demand        |
| NASA Exoplanet Archive | Exoplanet data          | Daily            |

### C. Related Documentation

- [Database Schema Documentation](./database-schema.md)
- [Event Contracts](../../contracts/nyx/README.md)
- [API Reference](./api-reference.md)
- [Deployment Guide](./deployment.md)
