Nest Backend Platform

Introduction

The Nest Backend Platform is Phenom’s comprehensive backend infrastructure hosted at https://nest.thephenom.app/ (production) and https://dev-nest.thephenom.app/ (staging). It consists of two primary components:

1. Hasura GraphQL + AWS Cognito – Authentication via Cognito JWT, data layer via Hasura on RDS Postgres
2. Admin Dashboard (N.E.S.T.) – Command center for UAP data management and monitoring

Access & Authentication

N.E.S.T. authenticates users with AWS Cognito. The admin frontend speaks to Cognito directly via the amazon-cognito-identity-js SDK and stores the resulting ID token in a Zustand store. That same token is forwarded to the nest-api Worker as a Bearer token, and the Worker forwards it again to Hasura so row-level security can be applied per user.

Authentication Flow

The Cognito JWT is the single source of identity throughout the request chain: Worker, Hasura, and any future services all verify it independently against the same Cognito JWKS endpoint.

Reference URLs:

• Amazon Cognito User Pools
• Hasura JWT Authentication
• Cognito JWT verification

Cognito User Pools

The frontend client ID is set per pool via VITE_COGNITO_CLIENT_ID. The Cognito region (us-east-1) and pool ID are also configured in the nest-api Worker via wrangler.toml so it can verify incoming Bearer tokens.

Sign-in Flows Supported

• Email + password (primary) – full sign-up, OTP email verification, sign-in, forgot-password, and reset-password flows are wired up. See admin_sandbox/phenom/src/features/auth/.
• Cognito is the sole gate for nest.thephenom.app and dev-nest.thephenom.app (the CF Access apps were deleted 2026-05-16). API routes use Cognito Bearer tokens exclusively. CF Access remains only on the nest-firebase snapshot.

Logout

The user dropdown in the sidebar calls useAuthStore.logout(), which signs out of the Cognito session via userPool.getCurrentUser().signOut() and navigates to /sign-in. The previous Cloudflare Access logout endpoint (/cdn-cgi/access/logout) is no longer used and was returning a 404 in dev.

Platform Architecture

Technology Stack

Frontend:

• React 18/19
• Vite (build tool)
• TanStack Router
• Apollo Client (GraphQL)
• Shadcn UI + Tailwind CSS

Backend:

• Hasura – GraphQL engine, fronted by an AWS ALB at api-staging.thephenom.app/v1/graphql (target group phenom-dev-graphql-tg)
• PostgreSQL – Primary database, schema managed by Hasura migrations in phenom-backend/hasura/migrations/default/
• AWS Cognito – User authentication. JWTs are verified by both the nest-api Worker and Hasura against the same JWKS endpoint
• nest-api Cloudflare Worker – API layer for all /api/* routes. Verifies Cognito JWT and forwards it to Hasura for row-level security. Handles events, lists, shares, users, notifications, teams, and S3 URL signing.

Deployment:

• Hosting: Cloudflare Pages / Netlify
• Functions: Cloudflare Workers
• Access Control: Cloudflare Zero Trust
• Infrastructure: AWS EC2 (development/staging)

System Architecture

The Cognito JWT is verified independently by both the Worker and Hasura. The Worker never holds long-lived credentials for Hasura – there is no admin secret in the request path. This means a stolen Worker secret cannot be used to read the database.

Key Services

1. AWS Cognito – User pool us-east-1_AkG9mnbjA (dev). Handles sign-up, OTP verification, sign-in, forgot/reset password.
2. Hasura GraphQL – Production: https://api.thephenom.app/v1/graphql; staging/dev: https://api-staging.thephenom.app/v1/graphql. Source of truth for all N.E.S.T. data: phenom, drops, users, lists, list_items, list_shares, item_shares, transcriptions, phenom_media, phenom_coords, phenom_sensor_data, phenom_shoots, and more. Schema managed by phenom-backend/hasura/migrations/default/.
3. nest-api Worker – Cloudflare Worker at admin_sandbox/nest-api/. All /api/* routes go through Hasura with the user’s forwarded Cognito JWT for row-level security.

Primary Use Cases

1. Global Phenomenon Monitoring

Track and manage UAP (Unidentified Anomalous Phenomena) events globally with:

• Real-time aircraft tracking via OpenSky Network API
• 3D globe visualization
• Interactive map views
• Location-based event data

2. User & Team Management

• Role-based access control
• Team member administration
• Permission management
• Activity logging

3. Data Collection & Organization

• Phenomenon event tracking
• Associated “shoots” (recording sessions)
• Geospatial data management
• Timestamp-based organization

4. Administrative Operations

• Dashboard analytics
• System settings
• Task management
• Notification system

Repository

GitHub: Phenom-earth/phenom-backend

Directory Structure:

phenom-backend/
├── server/phenom/              # Nhost React Apollo backend (legacy; current backend is Hasura + Cognito)
├── admin_sandbox/phenom/       # Admin dashboard application
├── adsb/                       # ADSB aircraft tracking service
│   ├── airnav/                 # AirNav RadarBox API CLI
│   └── run-phenoms/            # Phenom-to-aircraft correlation
├── db/
│   └── schema/                 # Database schemas
└── utils/                      # Deployment utilities

Authentication is handled by AWS Cognito + Hasura’s JWT verifier – no separate auth submodule.

External Integrations

OpenSky Network API

• Purpose: Real-time aircraft tracking data
• Integration: Proxied through Cloudflare Functions
• API Client: jonathan_at_phenom-api-client
• Features:
  • Token caching (Cloudflare Workers KV)
  • CORS handling
  • Automatic token refresh

AirNav RadarBox API

• Purpose: Real-time and historical aircraft tracking data for phenom correlation
• Integration: Direct API calls from ADSB service module
• Features:
  • Query flights by geographic area
  • Correlate aircraft positions with phenom sighting locations
  • Automatic phenom record updates with nearby aircraft data

Google Maps API

• Purpose: Map visualization and geocoding
• Usage: Admin dashboard map views

Firebase (retired)

• Project: phenom-7ee1a
• Status: Fully retired from the N.E.S.T. codebase. The firebase npm package, firebase.ts, firebase.json, and the functions/ directory have all been removed. The FIREBASE_SERVICE_ACCOUNT Worker secret should be deleted from Cloudflare.
• Historical context: Until April 2026 the /api/events endpoint queried Firestore live. All data was migrated to Hasura/Postgres via phenom-backend/hasura/scripts/migrate_firebase_to_postgres.py (idempotent backfill script). The backfill script remains available for any final Buzzard writes during sunset.

Security & Compliance

Authentication Security

• Cognito User Pools: SRP authentication, JWT-based sessions, refresh tokens
• JWT verification at every layer: The Worker and Hasura both verify the same JWT against Cognito JWKS independently. There is no shared admin secret or service account in the request path.
• Token storage: ID token held in memory by the Zustand authStore. Refresh tokens are persisted by amazon-cognito-identity-js to localStorage so the session survives reloads.
• Forgot/reset password: Email-based verification code flow via Cognito’s forgotPassword / confirmPassword APIs.

Access Control

• Cognito user pool: Only users provisioned in phenom-dev-local (or phenom-staging) can sign in
• Hasura row-level security: Permissions are evaluated against the JWT’s claims at query time. The nest-api Worker has no privileged data access of its own.
• Cognito-only gate: nest.thephenom.app and dev-nest.thephenom.app are not behind CF Access (apps deleted 2026-05-16); Cognito sign-in is the sole gate. API routes use Cognito Bearer tokens exclusively, with no CF_Authorization cookie auth. CF Access remains only on the nest-firebase snapshot.

Data Protection

• Encryption: TLS/SSL in transit
• Authentication: Required for all API access
• Authorization: Role-based data access
• Compliance: OAuth in development for enhanced security

Current Status

The Firebase → Cognito + Hasura migration is complete. All Worker routes use Cognito Bearer tokens and Hasura GraphQL. Firebase, D1, and CF Access cookie auth have been fully retired from the codebase.

Production (nest.thephenom.app) runs against the phenom-prod Cognito pool (us-east-1_knEL7cqS3) and the prod Synapse chat cluster (chat.thephenom.app). The dev surface (dev-nest.thephenom.app) uses phenom-dev-local for auth.

Open items:

• The FIREBASE_SERVICE_ACCOUNT Worker secret should be removed from Cloudflare (dead secret, firebase.ts was deleted).
• The ADSB service (/adsb/run-phenoms/) still reads phenom records from Firebase Firestore. Migration to Hasura is pending.
• The chat feature in features/chats/services/hasura-chat.ts queries tables dropped in Hasura migration 20260404. This code needs to be rewritten against Synapse/Matrix or removed.
• Avatar URLs in users.avatar_url reference mxc addresses on the old staging Synapse MXID. These must be re-uploaded against each user’s prod-pool MXID. See Chat Authentication for context.
• Synapse admin status must be re-granted per staff member after the prod pool migration. See Chat Authentication for context.

Authentication

Authentication is unified across N.E.S.T. and Synapse Chat via AWS Cognito. Production uses pool us-east-1_knEL7cqS3 (phenom-prod). See Infrastructure for the full pool and endpoint reference.

Related Documentation

• Admin Dashboard – feature overview and tech stack
• N.E.S.T. User Guide – end-user guide
• Infrastructure & Service Map – services, APIs, DNS, credentials
• Quality Dashboard – defect tracking and metrics
• ADS-B Aircraft Tracking – aircraft data integration
• Nhost Backend (Legacy) – deprecated backend reference
• Dev Stack Provisioning – EC2 setup guide

Support

For access issues or technical support, contact the internal development team or reference the GitHub repository.