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/.
• CF Access gates entry to N.E.S.T. domains at the network level, but all API routes use Cognito Bearer tokens exclusively.

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 — 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
├── 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.
• CF Access: Gates entry to N.E.S.T. domains at the network level. All API routes use Cognito Bearer tokens exclusively — no CF_Authorization cookie auth.

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

Development Status

Current Status (April 2026): Active development. 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.

Recently Shipped:

• Full Hasura migration (phenom-backend#196) — All nest-api routes (events, lists, items, shares, users, notifications) migrated from Firebase/D1 to Hasura GraphQL. Firebase npm package, firebase.ts, firebase.json, and functions/ directory removed. D1 binding removed.
• Cognito auth flow (phenom-backend#189, merged 2026-04-06) — Sign-in, sign-up, OTP verification, forgot-password, and reset-password forms wired to Cognito user pool phenom-dev-local.
• CI/CD pipeline — nest-ci.yml deploys Worker + Pages on merge to develop (dev-nest) and main (nest production). Path-filtered to admin_sandbox/**.
• Cloudflare DNS for Hasura — api-staging.thephenom.app CNAME → ALB for HTTPS access to Hasura.

In Progress / Follow-ups:

• ADSB aircraft tracking integration with AirNav RadarBox API
• Mobile Responsive Map (#56) — Draggable bottom sheet replaces sidebar overlay on mobile
• Remove FIREBASE_SERVICE_ACCOUNT Worker secret from Cloudflare (dead secret)

Known Limitations:

• The nest chat feature in features/chats/services/hasura-chat.ts queries chat_rooms / chat_members / chat_messages tables that were dropped in Hasura migration 20260404. Either these tables need to be re-added or the chat service needs to be rewritten against Synapse/Matrix.

Authentication

Authentication is now unified across NEST and Synapse Chat via AWS Cognito user pool us-east-1_n8gO6SbP6. See Infrastructure for details.

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.