Nest Backend Platform

Comprehensive overview of the Phenom Nest backend platform, including the Nhost authentication service and admin dashboard for UAP data management.

Introduction

The Nest Backend Platform is Phenom’s comprehensive backend infrastructure hosted at https://nest.thephenom.app/. It consists of two primary applications:

  1. Nhost Backend Service - Authentication, storage, and GraphQL API
  2. Admin Dashboard - Command center for UAP data management and monitoring

Access & Authentication

Authentication Flow

sequenceDiagram actor User participant Browser as Web Browser participant CF as Cloudflare Access participant GitHub as GitHub OAuth participant App as Nest Application User->>Browser: Navigate to nest.thephenom.app Browser->>CF: Request access CF->>Browser: Redirect to login Browser->>User: Show login page User->>Browser: Click "Sign in with GitHub" Browser->>GitHub: Redirect with Client ID GitHub->>User: Prompt for authorization User->>GitHub: Grant access GitHub->>Browser: Redirect with auth code Browser->>CF: Send auth code CF->>GitHub: Exchange code for token GitHub->>CF: Return access token CF->>CF: Validate team membership
(phenom-earth org)
(INT team) CF->>Browser: Grant access (set session cookie) Browser->>App: Access granted App->>User: Display dashboard Note over CF: Validates:
GitHub org: phenom-earth
Team: INT
Authorized users: smsmatt, others

Reference URLs:

Cloudflare Zero Trust OAuth

The Nest platform is secured using Cloudflare Zero Trust with OAuth-based authentication through GitHub.

Access Requirements:

  • GitHub Account: Must be a member of the phenom-earth organization
  • Team Membership: Must belong to the INT (Internal) team
  • Authorized Users: Including smsmatt and other internal team members

Access URL: When navigating to nest.thephenom.app, users will be redirected through Cloudflare Access login and authenticated via their GitHub account.

OAuth Providers

The platform supports multiple authentication methods:

  • GitHub OAuth (primary for team access)
  • Google OAuth
  • Apple OAuth
  • LinkedIn OAuth
  • Email/Password authentication
  • Magic link authentication
  • Security key (WebAuthn) authentication

Platform Architecture

Technology Stack

Frontend:

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

Backend:

  • Nhost - Open-source Firebase alternative
  • Hasura - GraphQL engine
  • PostgreSQL - Primary database
  • Firebase - Admin dashboard authentication

Deployment:

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

System Architecture

graph TB Client["Client Applications"] CF["Cloudflare Zero Trust
OAuth via GitHub"] subgraph "Nest Backend Platform" Frontend["Frontend
React 18/19 + Vite
TanStack Router
Apollo Client"] NhostBackend["Nhost Backend
Authentication + GraphQL"] AdminDash["Admin Dashboard
UAP Data Management"] end subgraph "Core Services" AuthService["Authentication Service
Port 9000
OAuth, Sessions, JWT"] GraphQLAPI["GraphQL API
Port 8080
Hasura + PostgreSQL"] StorageService["Storage Service
Port 9500
File Management"] FunctionsService["Functions Service
Port 9999
OpenSky API Proxy"] end subgraph "External Services" OpenSky["OpenSky Network API
Aircraft Tracking"] GoogleMaps["Google Maps API
Geocoding & Maps"] Firebase["Firebase
Firestore Data"] end Client --> CF CF --> Frontend Frontend --> NhostBackend Frontend --> AdminDash NhostBackend --> AuthService NhostBackend --> GraphQLAPI NhostBackend --> StorageService AdminDash --> GraphQLAPI GraphQLAPI --> OpenSky GraphQLAPI --> GoogleMaps AdminDash --> Firebase style CF fill:#ffd700 style AuthService fill:#e1f5ff style GraphQLAPI fill:#f3e5f5 style StorageService fill:#e8f5e9 style FunctionsService fill:#fff3e0

Reference URLs:

Key Services

  1. Authentication Service (http://localhost:9000/v1/auth)

    • User registration and login
    • OAuth provider integration
    • Session management
    • Token refresh

  2. GraphQL API (http://localhost:8080/v1/graphql)

    • Hasura-powered GraphQL endpoint
    • Real-time subscriptions
    • Role-based access control

  3. Storage Service (http://localhost:9500/v1/storage)

    • File upload and management
    • Image processing
    • Secure file access

  4. Serverless Functions (http://localhost:9999/v1/functions)

    • OpenSky API proxy (aircraft tracking)
    • Custom business logic

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
├── db/
│   ├── schema/                 # Database schemas
│   └── hasura-auth/            # Authentication submodule
└── utils/                      # Deployment utilities

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

Google Maps API

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

Firebase

  • Project: phenom-7ee1a
  • Purpose: Admin dashboard authentication and data storage
  • Database: Firestore for phenomenon data

Security & Compliance

Authentication Security

  • Multi-factor Authentication: WebAuthn/Security keys supported
  • Session Management: Secure token-based sessions
  • OAuth 2.0: Industry-standard OAuth flows
  • Zero Trust Architecture: Cloudflare Access integration

Access Control

  • Organization-level: phenom-earth GitHub organization
  • Team-level: INT team membership required
  • Role-based: Granular permission system
  • Audit Logging: User activity tracking

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 Version: Admin Dashboard v1.3.0 (April 2025)

In Development:

  • Enhanced OAuth implementation
  • Additional security features
  • Expanded phenomenon tracking capabilities

Known Limitations:

  • Phenomenon deletion disabled until OAuth completion
  • Local development configured for localhost URLs

Support

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

Admin Dashboard (Phenom Global Command Center)

Detailed documentation for the Phenom Global Command Center admin dashboard, featuring UAP monitoring, map views, and team management capabilities.

Nhost Backend Service

Technical documentation for the Nhost backend service providing authentication, GraphQL API, and storage capabilities for the Phenom platform.

Phenom Dev Stack Provisioning

Instructions for provisioning an EC2 instance from scratch for the DEV Phenom backend, including Git and Docker setup.