Internet Architecture

Categories:

• INT

High-Level Architecture Overview

This diagram provides a simplified view of the major components and their interactions.

graph TD
    U[Users] --> WP[Web Presence]
    U --> MA[Mobile App]
    MA --> BE[Backend Services]
    %% Dashed line indicates potential or indirect interaction
    WP -.-> BE

    CM[Code Management] -- Deploys or Builds --> WP
    CM -- Deploys or Builds --> MA
    CM -- Deploys or Builds --> BE

    subgraph Web Presence
        CFP[Cloudflare Pages Sites]
        WPH[WordPress Site]
        ETSY[Etsy Store]
    end

    subgraph Mobile App
        IOS[iOS App]
        AND[Android App]
    end

    subgraph Backend Services
        FB[Firebase/GCP]
        GCS[Cloud Storage]
        AWS[AWS]
    end

    subgraph Code Management
        GH[GitHub Repos]
    end

    classDef component fill:#1a1a1a,stroke:#d73429,stroke-width:2px,color:#ffffff,rx:30;
    class WP,MA,BE,CM component;

Component Details

The following sections provide more detailed diagrams for specific parts of the architecture.

Web Presence: User Access & Platforms

This diagram shows how users access the various web platforms.

graph LR
    subgraph User_Interaction
        U_GEN[Users]
        U_INT[INT team]
        U_EXT[EXT team]
    end

    subgraph Platforms
        GH["<a href='https://github.com/phenom-earth' target='_blank'>GitHub</a>"]
        CFP[Cloudflare Pages]
        WPH["<a href='https://phenom.earth/' target='_blank'>phenom.earth (Old Site)</a>"]
        ETSY["<a href='https://www.etsy.com/shop/phenomenation/' target='_blank'>Etsy Store</a>"]
    end

    subgraph Cloudflare_Pages_Sites
        direction LR
        WWW["<a href='https://www.thephenom.app/' target='_blank'>www.thephenom.app</a>"]
        INT_DOCS["<a href='https://int-docs.thephenom.app/' target='_blank'>int-docs.thephenom.app</a>"]
        NEST["<a href='https://nest.thephenom.app/' target='_blank'>nest.thephenom.app</a>"]
    end

    %% Connections
    U_GEN -- Accesses --> WWW
    U_GEN -- Accesses --> WPH
    U_GEN -- Accesses --> ETSY
    
    U_INT -- Accesses --> INT_DOCS
    U_INT -- Accesses --> NEST
    U_INT -- Accesses --> GH

    U_EXT -- Accesses --> GH

    GH -- Deploys_to --> CFP
    CFP -- Hosts --> WWW
    CFP -- Hosts --> INT_DOCS
    CFP -- Hosts --> NEST

Web Presence: Code Management & Deployment

This diagram illustrates the relationship between GitHub repositories, the teams managing them, and where the code is deployed.

graph LR
    %% Changed to LR for better flow
    subgraph Code_Management [GitHub: Phenom-earth]
        subgraph Repositories
            GH_WWW[phenom-www]
            GH_DOCS[phenom-earth-docs]
            GH_ECHO[phenom-echo]
            GH_MERCH[phenom-merch]
            GH_BACKEND[phenom-backend-nest]
            GH_RXN[PhenomRxn]
            GH_BUZZARD_IOS[Buzzard-ios]
            GH_BUZZARD_AND[Buzzard-Android]
        end
        subgraph Teams
            T_MARCOM[Marcom Team]
            T_INT[INT Team]
            T_EXT[EXT Team]
            T_ECHO[ECHO Team]
            T_MERCH[Merch Team]
        end
    end

    subgraph Deployment_Targets
        CFP[Cloudflare Pages]
        WPH[WordPress Hosting]
        AS[Apple App Store]
        PS[Google Play Store]
        EXPO[expo.dev]
        BETA_DEVICES[Beta-Tester Devices]
        FB_DEPLOY[Firebase]
    end

    %% Team Management & Deployment
    T_MARCOM -- Manages --> GH_WWW
    GH_WWW -- Deploys_to --> CFP

    T_INT -- Manages --> GH_DOCS
    T_INT -- Manages --> GH_BACKEND
    T_INT -- Manages --> GH_RXN

    T_EXT -- Manages --> GH_BUZZARD_IOS
    T_EXT -- Manages --> GH_BUZZARD_AND

    GH_BUZZARD_IOS -- Deploys_via --> FB_DEPLOY
    GH_BUZZARD_AND -- Deploys_via --> FB_DEPLOY
    FB_DEPLOY -- Deploys_to --> AS
    FB_DEPLOY -- Deploys_to --> PS

    GH_DOCS -- Deploys_to --> CFP
    GH_BACKEND -- Deploys_to --> CFP
    GH_RXN -- Deploys_to --> EXPO
    EXPO -- Deploys_to --> BETA_DEVICES

    T_ECHO -- Manages --> GH_ECHO
    GH_ECHO -- Deploys_to --> WPH

    T_MERCH -- Manages --> GH_MERCH
    %% Merchandise repo managed here, deployed elsewhere (see Merchandise Flow)

    %% Styling
    classDef team fill:#d73429,stroke:#b82a21,stroke-width:2px,color:#ffffff,rx:30;
    class T_MARCOM,T_INT,T_EXT,T_ECHO,T_MERCH team;

Web Presence: Merchandise Flow

This diagram focuses specifically on the merchandise management and update process.

graph TD
    subgraph Code_Management [GitHub: Phenom-earth]
         GH_MERCH[phenom-merch]
         T_MERCH[Merch Team]
    end

    subgraph Third_Party ["Third Party"]
        ETSY[Etsy Store]
    end

    %% Merchandise Flow
    T_MERCH -- Manages --> GH_MERCH
    T_MERCH -- Updates --> ETSY
    GH_MERCH -- Contains_Assets_for --> ETSY

    %% Styling
    classDef team fill:#d73429,stroke:#b82a21,stroke-width:2px,color:#ffffff,rx:30;
    class T_MERCH team;

Mobile App Architecture (The Phenom App - Codename: Project Buzzard)

graph TD
    direction LR
    subgraph User_Interaction
        U[Users]
        MA[Mobile App iOS_Android]
    end
    subgraph Backend_Services ["Backend (Firebase/GCP)"]
        FB[Firebase Backend_Auth]
        GCS[Google Cloud Storage User_Content]
    end
    subgraph Distribution
        AS[Apple App Store]
        PS[Google Play Store]
    end
    subgraph Code_Management [GitHub: Phenom-earth]
        GH_BUZZARD_IOS[Buzzard-ios]
        GH_BUZZARD_AND[Buzzard-Android]
        T_EXT[EXT Team]
    end

    U -- Uses --> MA
    MA -- Connects_to --> FB
    MA -- Accesses --> GCS
    FB -- Interacts_with --> GCS
    %% MA -- Distributed_via --> AS %% Replaced by repo deployment
    %% MA -- Distributed_via --> PS %% Replaced by repo deployment

    T_EXT -- Manages --> GH_BUZZARD_IOS
    T_EXT -- Manages --> GH_BUZZARD_AND
    GH_BUZZARD_IOS -- Connects_to --> Backend_Services
    GH_BUZZARD_AND -- Connects_to --> Backend_Services
    GH_BUZZARD_IOS -- Deploys_to --> AS
    GH_BUZZARD_AND -- Deploys_to --> PS
    %% 'Buzzard' is the codename for the Phenom App mobile client

    %% Styling
    linkStyle default interpolate basis
    classDef team fill:#d73429,stroke:#b82a21,stroke-width:2px,color:#ffffff,rx:30;
    class T_EXT team;

AWS Infrastructure

This diagram shows the AWS setup for our services.

graph TD
    subgraph "AWS Cloud"
        subgraph "VPC"
            subgraph "Public Subnet"
                ELB[Elastic Load Balancer]
            end
            subgraph "Private Subnet"
                ECS[ECS Cluster]
                RDS[RDS Database]
            end
        end
        S3[S3 for Static Assets]
        CF[CloudFront]
    end

    U[Users] --> CF
    CF --> S3
    CF --> ELB
    ELB --> ECS
    ECS --> RDS

(Note: Documentation hosting via CloudFront and Backup Storage (TBD) are omitted from these specific diagrams for clarity but remain relevant to the overall infrastructure.)

Key Components & Services

1. Email

• Primary Domain: thephenom.app
• Provider: Amazon WorkMail
• Legacy Domain: phenom.earth (hosted by OrangeHost)

2. Website Hosting

• Provider: OrangeHost

• Services: Hosts the old phenom.earth website (now only for social media WordPress).

• SSL: Provided by Let’s Encrypt, likely managed via OrangeHost control panel or server configuration.

• Provider: Cloudflare

• Services Hosts all sites for thephenom.app (nest, try, www, int-docs).

3. Mobile App Backend & Authentication

• Provider: AWS (Cognito + Hasura + RDS)
• Services: User authentication via Cognito (phenom-staging pool, us-east-1_n8gO6SbP6). GraphQL via Hasura at https://api.thephenom.app/v1/graphql. Postgres 17.4 on RDS (db.m5.large). See Phenom Production Environment for full details.
• Legacy note: An earlier Firebase/GCP backend existed. It has been superseded by the AWS stack.

4. User Content Storage

• Provider: AWS S3
• Bucket: phenom-prod-media-storage
• Purpose: Stores user-generated content (phenom uploads) via presigned PUT URLs issued by the action-handler Lambda.

5. Documentation Hosting

• Provider: Cloudflare Pages
• Sites: int-docs.thephenom.app (internal docs, this site), www.thephenom.app (marketing), nest.thephenom.app (N.E.S.T. SPA).

6. Mobile App Distribution

• Platforms: Apple App Store, Google Play Store
• Purpose: Official channels for users to download and update the The Phenom App mobile application.

7. Code Repositories

• Provider: GitHub
• Purpose: Stores all source code for the website, mobile app, backend services, and documentation.

8. Domain Name System (DNS)

• Provider: Cloudflare
• Account: pavestar@protonmail.com
• Details: Cloudflare manages the DNS for thephenom.app. This is also where the Cloudflare Workers are managed.
• Records:
  • phenom.earth points to OrangeHost.
  • thephenom.app MX records point to Amazon WorkMail.
  • int-docs.thephenom.app, nest.thephenom.app, and try.thephenom.app are managed via Cloudflare Workers.

9. Cloudflare Workers

• Description: Serverless execution environment used for hosting various services.
• Hosted Services:
  • int-docs.thephenom.app: Internal documentation site.
  • nest.thephenom.app: Backend services.
  • https://try.thephenom.app: A QR code service that routes visitors to the correct app store (iOS/Android) and tracks user visits.

10. Backup Storage

• RDS: 7-day automated backup retention, 03:00–04:00 UTC window. Final snapshot enabled on destroy.
• S3 / Terraform state: Versioning enabled on phenom-prod-media-storage and phenom-production-tfstate.
• Other backup strategy: Not yet formally defined beyond RDS and S3 versioning.

11. Monitoring & Logging

• CloudWatch: Lambda invocation logs under /aws/lambda/phenom-prod-*. ECS Container Insights enabled on phenom-prod-cluster. SES Send metric tracked under AWS/SES.
• Dedicated observability solution: Not yet deployed.

12. AWS Services (live production)

• Cognito: Three user pools. See Cognito Authentication Flows.
• SES: noreply@thephenom.app identity, DKIM-signed, SPF + DMARC. See Cognito Email via SES.
• ALB: phenom-prod-alb, internet-facing, routes api.thephenom.app to Hasura.
• ECS Fargate: phenom-prod-cluster, one graphql task (nhost/graphql-engine:v2.48.5-ce).
• RDS: phenom-prod-postgres, Postgres 17.4, db.m5.large, private subnets.
• Lambda: Three functions (action-handler, cognito-trigger, cognito-sync-users).
• WorkMail: Organisation m-85dbc6db1b474331af97f5ce0e777740 for thephenom.app email.

Security Considerations

• SSL/TLS: Enforced via ACM wildcard (*.thephenom.app) on ALB; Cloudflare manages TLS for Pages sites.
• RDS: Private subnets only, no public access, AES256 encrypted storage, deletion protection enabled.
• S3: All production buckets have public access fully blocked.
• Cognito: Self-signup disabled on all pools. Admin-only user creation enforced.
• Secrets: Stored in AWS Secrets Manager (phenom-prod-app-secrets, rds/phenom-prod-db/credentials). Never committed to source.
• GitHub Security: Branch protection rules, OIDC-based CI authentication (no long-lived access keys in CI).
• Regular Audits: Recommended for all components.