Eve library

Nyx Cosmic Observatory - Microservices Architecture

Guide

Revision 1

On this page

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#

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

text
# 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:

text
# 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:

text
# 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:

text
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:

text
# 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#

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

text
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

text
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

text
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

text
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#

text
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#

text
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#

text
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