Infrastructure & Service Map

Service Architecture

                    ┌─────────────────────────────────────────────┐
                    │              User's Browser                  │
                    │  ┌─────────────────────────────────────────┐ │
                    │  │  N.E.S.T. SPA (React + CesiumJS)       │ │
                    │  │  - 3D Globe with Google Photorealistic  │ │
                    │  │  - Marker rendering (UFO/airplane SVG)  │ │
                    │  │  - Day/night imagery blending           │ │
                    │  └──────────┬──────────┬──────────┬────────┘ │
                    └─────────────┼──────────┼──────────┼──────────┘
                                  │          │          │
                    ┌─────────────▼──┐  ┌────▼────┐  ┌─▼──────────┐
                    │ Cloudflare     │  │Firebase │  │ nest-api   │
                    │ Access (OAuth) │  │Firestore│  │ (CF Pages  │
                    │                │  │         │  │  Functions)│
                    └────────────────┘  └────┬────┘  └─────┬──────┘
                                             │             │
                              ┌──────────────┴──┐    ┌────▼─────┐
                              │  AWS S3          │    │ CF D1    │
                              │  (Drop media)    │    │ (Lists,  │
                              │                  │    │  Users)  │
                              └──────────────────┘    └──────────┘

Deployments

Deployment Commands

# Build on ai.matthewstevens.org (Apple Silicon, has Node + npm)
ssh ai "cd .../admin_sandbox/phenom && npx vite build"

# Deploy to dev-nest CF Pages
wrangler pages deploy dist --project-name=dev-nest-phenom --branch=main

# Production deploys automatically via Netlify on push to main

Authentication

Cloudflare Access (Login Gate)

Access Apps (all use the same IdP):

GitHub App (Team Data)

Data Sources

Firebase Firestore

Firebase Project: phenom-7ee1a Auth: Email/password service account Credentials: .env file (VITE_FIREBASE_AUTH_EMAIL, VITE_FIREBASE_AUTH_PASSWORD) Must be baked into build: Yes — Vite replaces import.meta.env.VITE_* at build time

AWS S3 (Drop Media)

CORS Configuration (docs/s3-cors.json) — two rules as of 2026-03-14:

Rule 1 — N.E.S.T. origins (GET, HEAD):

• https://nest.thephenom.app
• https://dev-nest.thephenom.app
• https://phenom.matthewstevens.org

Rule 2 — Drop origins (GET, PUT, HEAD; exposes ETag header):

• https://www.thephenom.app
• https://thephenom.app

Drop origins require PUT for presigned URL uploads and HEAD for integrity checks. The ETag exposed header is needed so the client can verify upload success.

Bucket Policy Referers (docs/s3-bucket-policy.json):

• https://nest.thephenom.app/*
• https://dev-nest.thephenom.app/*
• https://phenom.matthewstevens.org/*

Cloudflare D1 (Lists & Users)

Schema: admin_sandbox/nest-api/schema.sql

API Endpoints

nest-api (CF Pages Functions)

Lives at: admin_sandbox/phenom/functions/api/[[path]].js

All endpoints require CF_Authorization cookie (CF Access JWT).

Drop Upload API (AWS Lambda)

Drop Backend (Python)

Drop Upload Flow

User (phenom-drop web app)
  │
  ├─1─▶ Verify C2PA credentials (client-side)
  │
  ├─2─▶ POST /api/drop/send-password
  │      → Backend sends 6-char OTP via Brevo email
  │
  ├─3─▶ POST /api/drop/verify-password
  │      → Backend validates OTP + registers hash
  │
  ├─4─▶ POST /api/drop/upload
  │      → Backend proxies to AWS Lambda
  │      → Lambda returns presigned S3 PUT URL
  │      → Backend writes metadata to Firestore `drops` collection
  │
  ├─5─▶ PUT to S3 presigned URL (direct upload from browser)
  │      → File stored at s3://phenom-dev-media-staging/uploads/...
  │      → S3 CORS Rule 2 allows PUT from Drop origins
  │
  └─6─▶ Backend updates Firestore with mediaUrl + s3Key
         → N.E.S.T. PhenomFetcher reads this to display image

Note (2026-03-14): computeFileHash() in www/web/drop.html now uses streaming SHA-256 (chunked reads via ReadableStream) for files >100MB. This avoids loading the entire file into memory at once, preventing browser tab crashes on large uploads.

Credential Locations (GPG Pass)

CesiumJS Globe Configuration

Imagery Layers (bottom to top)

Google Maps Tile API

Day/Night Effects

Clock

• Default: current real time (JulianDate.now())
• On marker click: jumps to recording timestamp
• On deselect: resets to real time
• shouldAnimate = false — time only changes on marker selection

Build & Deploy Checklist

Before deploying any changes:

1. Firebase .env must exist on build server (ai): VITE_FIREBASE_AUTH_EMAIL, VITE_FIREBASE_AUTH_PASSWORD
2. Google Maps key is hardcoded in CesiumGlobe.tsx (not an env var)
3. S3 CORS must include the deployment domain
4. D1 binding must be configured in CF Pages project settings
5. CF Access must have an app + policy for the deployment domain
6. OAuth App callback must be https://thephenom-app.cloudflareaccess.com/cdn-cgi/access/callback

Last Updated: 2026-03-14