# Nyx CDN Configuration

> Content Delivery Network configuration for astronomical static assets

This directory contains the CDN configuration for distributing Nyx static assets
including star textures, planet images, nebula photographs, and catalog data.

## Overview

The Nyx CDN is designed to efficiently serve large astronomical assets with
appropriate caching policies based on content update frequency.

## Asset Categories

### Textures (Immutable, 1 Year Cache)

| Path                        | Content                                  | Size Range | Format    |
| --------------------------- | ---------------------------------------- | ---------- | --------- |
| `/textures/stars/`          | Star sprite sheets, sky background tiles | 1-50 MB    | PNG, WebP |
| `/textures/planets/`        | Planet surface textures, normal maps     | 10-200 MB  | JPG, PNG  |
| `/textures/nebulae/`        | Nebula photographs, emission maps        | 5-100 MB   | JPG, PNG  |
| `/textures/galaxies/`       | Galaxy images, morphology maps           | 5-100 MB   | JPG, PNG  |
| `/textures/constellations/` | Constellation artwork                    | 1-10 MB    | SVG, PNG  |
| `/textures/milkyway/`       | Milky Way panoramas                      | 50-500 MB  | JPG       |

### Catalog Data (7 Day Cache)

| Path                    | Content                         | Size Range | Format       |
| ----------------------- | ------------------------------- | ---------- | ------------ |
| `/catalogs/hipparcos/`  | Hipparcos star catalog          | 50 MB      | JSON, Binary |
| `/catalogs/gaia/`       | Gaia DR3 subsets by region      | 100-500 MB | Binary       |
| `/catalogs/tycho/`      | Tycho-2 catalog                 | 200 MB     | Binary       |
| `/catalogs/messier/`    | Messier object data             | 1 MB       | JSON         |
| `/catalogs/ngc/`        | NGC/IC catalog                  | 10 MB      | JSON         |
| `/data/constellations/` | Constellation boundaries, lines | 5 MB       | JSON         |

### Dynamic Data (1 Hour Cache)

| Path               | Content                              | Size Range | Format    |
| ------------------ | ------------------------------------ | ---------- | --------- |
| `/data/tle/`       | Two-Line Element sets for satellites | 5 MB       | TLE, JSON |
| `/data/events/`    | Upcoming astronomical events         | 100 KB     | JSON      |
| `/data/ephemeris/` | Pre-computed ephemeris data          | 10 MB      | Binary    |

## Directory Structure

```
cdn.nyx.oshun.io/
├── textures/
│   ├── stars/
│   │   ├── sprites/           # Star sprite atlases
│   │   ├── backgrounds/       # Sky background tiles
│   │   └── milkyway/          # Milky Way textures
│   ├── planets/
│   │   ├── mercury/           # 2K-8K surface textures
│   │   ├── venus/
│   │   ├── earth/
│   │   ├── mars/
│   │   ├── jupiter/
│   │   ├── saturn/
│   │   ├── uranus/
│   │   ├── neptune/
│   │   └── moons/             # Major moon textures
│   ├── nebulae/
│   │   ├── emission/          # H-alpha, OIII images
│   │   ├── planetary/         # Planetary nebulae
│   │   └── reflection/        # Reflection nebulae
│   └── galaxies/
│       ├── spiral/
│       ├── elliptical/
│       └── irregular/
├── catalogs/
│   ├── hipparcos/
│   ├── gaia/
│   │   └── healpix/           # HEALPix partitioned data
│   ├── tycho/
│   ├── messier/
│   └── ngc/
├── data/
│   ├── constellations/
│   │   ├── boundaries.json
│   │   ├── lines.json
│   │   └── mythology/
│   ├── tle/
│   │   ├── stations.tle       # Space stations
│   │   ├── visual.tle         # Visible satellites
│   │   └── starlink.tle       # Starlink constellation
│   ├── events/
│   │   ├── 2026.json
│   │   └── current.json
│   └── ephemeris/
│       └── planets/
└── audio/
    ├── tours/                 # Narrated tour audio
    └── ambient/               # Ambient space sounds
```

## Cache Policies

### Immutable Assets (1 Year)

- Star textures
- Planet textures
- Nebula images
- Galaxy images
- Constellation artwork

These assets are versioned via filename hash and never change once published.
Browser and CDN caching is maximized.

```
Cache-Control: public, max-age=31536000, immutable
```

### Catalog Data (7 Days)

- Star catalogs
- DSO catalogs
- Constellation data

Updated infrequently, typically with new data releases (Gaia DR4, etc.).

```
Cache-Control: public, max-age=604800
```

### Dynamic Data (1 Hour)

- TLE data (updated hourly)
- Event data (updated daily)
- Pre-computed ephemeris

```
Cache-Control: public, max-age=3600, stale-while-revalidate=86400
```

## Deployment

### Prerequisites

1. AWS account with CloudFront access
2. ACM certificate for `cdn.nyx.oshun.io`
3. Route53 hosted zone (or external DNS)

### Apply Configuration

```bash
cd infra/nyx/cdn

# Initialize Terraform
terraform init

# Plan changes
terraform plan -var="environment=prod" -var="certificate_arn=arn:aws:acm:..."

# Apply
terraform apply -var="environment=prod" -var="certificate_arn=arn:aws:acm:..."
```

### Upload Assets

```bash
# Sync textures (with immutable caching)
aws s3 sync ./textures s3://nyx-static-assets-prod/textures \
  --cache-control "public, max-age=31536000, immutable"

# Sync catalogs (with medium caching)
aws s3 sync ./catalogs s3://nyx-static-assets-prod/catalogs \
  --cache-control "public, max-age=604800"

# Sync dynamic data (with short caching)
aws s3 sync ./data s3://nyx-static-assets-prod/data \
  --cache-control "public, max-age=3600"
```

### Invalidate Cache

```bash
# Invalidate specific path
aws cloudfront create-invalidation \
  --distribution-id DISTRIBUTION_ID \
  --paths "/data/tle/*"

# Invalidate all (use sparingly)
aws cloudfront create-invalidation \
  --distribution-id DISTRIBUTION_ID \
  --paths "/*"
```

## Performance Optimization

### Image Formats

| Use Case        | Format                      | Why                                  |
| --------------- | --------------------------- | ------------------------------------ |
| Star sprites    | WebP                        | Excellent compression, alpha support |
| Planet textures | JPG (surface), PNG (clouds) | JPG for photos, PNG for transparency |
| Nebulae         | JPG                         | Photo content compresses well        |
| UI elements     | SVG/WebP                    | Scalable or compressed               |

### Compression

- Brotli compression enabled for text-based formats
- Gzip fallback for older browsers
- Pre-compressed assets where possible

### Tile Sizes

| Content Type    | Tile Size | Reason                          |
| --------------- | --------- | ------------------------------- |
| Star background | 512×512   | Balance load time and coverage  |
| Planet textures | 1024×1024 | Detail without excessive memory |
| Nebula images   | 2048×2048 | High detail for zoom            |

## Monitoring

### CloudWatch Metrics

- Request count
- Cache hit ratio
- 4xx/5xx error rate
- Bandwidth consumption
- Origin latency

### Alerts

Configure alerts for:

- Cache hit ratio < 90%
- Error rate > 1%
- Origin latency > 500ms

## Cost Estimation

| Asset Type   | Storage   | Requests/Month | Estimated Cost |
| ------------ | --------- | -------------- | -------------- |
| Textures     | 50 GB     | 10M            | ~$15/month     |
| Catalogs     | 10 GB     | 5M             | ~$8/month      |
| Dynamic data | 1 GB      | 50M            | ~$25/month     |
| **Total**    | **61 GB** | **65M**        | **~$48/month** |

_Costs vary by region and actual usage._

## Security

- TLS 1.2+ required
- CORS configured for application origins
- No direct S3 access (CloudFront only)
- Security headers via CloudFront Function
- Rate limiting at edge

## Related Documentation

- [Nyx Deployment Guide](../README.md)
- [Star Map Development](../../../apps/nyx/star-map/README.md)
- [Asset Pipeline](../../../docs/domains/nyx/asset-pipeline.md)
