# modelearth/cloud architecture

> Architecture diagram of the GitHub repository modelearth/cloud, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/modelearth/cloud
- Repository: https://github.com/modelearth/cloud

## Overview

##### Project type and purpose
- This is a infrastructure-as-code and deployment repo (“ModelEarth Cloud”) for hosting Flask-based micro-services and static sites on Google Cloud Run and GitHub Pages.
- It provides a template (“run/”) for running interactive notebooks and web routes via Flask in Cloud Run containers, a “cloud-main” experimental folder, and a “team/2025” directory for individual student deployments (including one Firebase+Flask example).

##### File structure
Top-level directories:
- run/    → Flask app code, container config, notebooks, utilities, deployment scripts
- cloud-main/ → an earlier or alternate Flask deployment skeleton
- team/2025/ → per-developer subfolders (static GitHub Pages, one Firebase auth demo)
Key files under run/:
– app.py, app_local.py, app_unified.py, app_minimal.py
– routes/core_routes.py, routes/notebook_runner.py
– utils/*.py (auth, config, GitHub IO, notebook execution)
– config.yaml, .env.example, requirements.txt, Dockerfile, deploy.sh
– notebooks (.ipynb) and static html/js pages
Deployment:
– Dockerfile + deploy.sh for building/pushing to Cloud Run
– .gcloudignore/.dockerignore to control artifacts
– rotate-token.sh, fix_imports.py for operational tasks
team/2025/<handle> folders: static GitHub Pages sites (index.html + README), one Firebase+Flask example with app.yaml and templates.

##### README insights
- Primary goal: spin up a Flask site on Cloud Run to host RealityStream notebooks and ML demos.
- Integration with GitHub Pages for team sub-sites.
- References to Firebase Auth example in team/2025/revanth.
- Emphasis on not storing data in repo; notebook traffic and APIs used at runtime.

##### Components & interactions
a. Main components
- Users (developers & end-users in browser)
- Static Hosting (GitHub Pages for cloud/ and team sites)
- Cloud Run Service (containerized Flask app)
- Flask App Modules
– HTTP router (core_routes.py)
– Notebook runner (notebook_runner.py)
– Utilities (auth_utils, github_utils, notebook_utils, config_utils)
- Configuration & Secrets
– config.yaml, environment variables (.env)
- External Services
– GitHub APIs (for notebook or data retrieval)
– Google Cloud Logging/Monitoring
– (Optional) Firebase Auth & Firestore in team/2025/revanth
b. Relationships & data flow
1. User → Browser → HTTP Request to Cloud Run endpoint
2. Flask router parses route → calls appropriate handler (core or notebook runner)
3. Handler uses utils/config to load secrets → uses GitHub APIs or local filesystem to fetch notebooks/data
4. Notebook runner executes .ipynb (via notebook_utils) → renders HTML/JSON → returns to user
5. Static assets (index.html, JS) served directly from container or via GitHub Pages for team sub-sites
6. Deployment pipeline: commit → Docker build → gcloud run deploy
c. Architectural patterns & design principles
– Modular code organization (routes vs utils)
– Multiple entrypoint scripts (app.py vs app_local.py vs app_unified.py) for local vs minimal vs unified modes
– Containerization as micro-service on Cloud Run
– Separation of concerns: static hosting (GitHub Pages) vs dynamic compute (Cloud Run)
d. Key technologies
– Python Flask
– Docker / Google Cloud Run
– GitHub Pages for static content
– Jupyter Notebooks (.ipynb) execution at runtime
– Firebase Auth & Hosting (optional example)
– Shell scripts (deploy.sh, rotate-token.sh)

##### Capturing essential elements
– Show per-developer static sites under GitHub Pages as independent sub-sites.
– Include config layer (config.yaml + .env) feeding into utils/config_utils.
– Represent notebooks (.ipynb) as assets executed at runtime by notebook_utils.

## Diagram (Mermaid)

```mermaid
flowchart TB
  %% User Layer
  subgraph "User Interaction"
    direction TB
    User["End User / Developer"]:::external
    Browser["Web Browser"]:::external
  end

  User -->|uses| Browser
  Browser -->|HTTP Request| CloudRun["Cloud Run Container"]:::compute

  %% Static Hosting
  subgraph "Static Hosting (GitHub Pages)" 
    direction TB
    StaticRepo["ModelEarth Cloud Pages"]:::static
  end
  Browser -->|loads static site| StaticRepo

  %% Cloud Run Service
  subgraph "Cloud Run Service" 
    direction TB
    CloudRun
    subgraph "Flask App" 
      direction TB
      Entrypoints["Entrypoint Scripts"]:::compute
      subgraph "Routes (Controllers)"
        direction TB
        CoreRoutes["Flask Router<br/>(core_routes.py)"]:::compute
        NotebookRoutes["Notebook Runner<br/>(notebook_runner.py)"]:::compute
      end
      subgraph "Utils (Services)"
        direction TB
        AuthUtils["Auth Utils<br/>(auth_utils.py)"]:::data
        ConfigUtils["Config Utils<br/>(config_utils.py)"]:::data
        GitHubUtils["GitHub Utils<br/>(github_utils.py)"]:::data
        NotebookUtils["Notebook Utils<br/>(notebook_utils.py)"]:::data
        CompatUtils["Compat Helpers<br/>(compat_utils.py)"]:::data
      end
      Entrypoints -->|routes to| CoreRoutes
      Entrypoints -->|routes to| NotebookRoutes
      CoreRoutes -->|uses| AuthUtils
      CoreRoutes -->|loads config| ConfigUtils
      CoreRoutes -->|calls| GitHubUtils
      NotebookRoutes -->|executes| NotebookUtils
      NotebookRoutes -->|loads config| ConfigUtils
    end
  end

  %% External Services
  subgraph "External Services" 
    direction TB
    GitHubAPI["GitHub API"]:::external
    CloudLogging["GCP Logging/Monitoring"]:::external
  end
  CoreRoutes -->|API calls| GitHubAPI
  NotebookRoutes -->|logs| CloudLogging
  CloudRun -->|logs & metrics| CloudLogging

  %% Config & Assets
  subgraph "Configuration & Assets"
    direction TB
    ConfigYAML["config.yaml"]:::data
    EnvFile[".env"]:::data
    Notebooks["Notebooks (.ipynb)"]:::data
    StaticAssets["Static Assets (HTML/JS)"]:::static
  end
  ConfigYAML -->|reads| ConfigUtils
  EnvFile -->|env vars| ConfigUtils
  Notebooks -->|runtime| NotebookUtils
  StaticAssets -->|served| CloudRun

  %% Deployment Pipeline
  subgraph "Deployment Pipeline"
    direction TB
    Dockerfile["Dockerfile"]:::pipeline
    DeploySh["deploy.sh"]:::pipeline
    GcloudIgnore[".gcloudignore"]:::pipeline
    DockerIgnore[".dockerignore"]:::pipeline
    RotateToken["rotate-token.sh"]:::pipeline
    FixImports["fix_imports.py"]:::pipeline
  end
  Dockerfile -->|build image| CloudRun
  DeploySh -->|deploy| CloudRun
  GcloudIgnore -->|ignore rules| Dockerfile
  DockerIgnore -->|ignore rules| Dockerfile
  RotateToken -->|refresh| Entrypoints
  FixImports -->|fix imports| Entrypoints

  %% Team Static Sites
  subgraph "Team Static Sites (GitHub Pages)"
    direction TB
    Jainam["Jainam Site"]:::static
    Praneeth["Praneeth Site"]:::static
    Akshay["Akshay Site"]:::static
    Lorenh["lorenh Site"]:::static
    Priyanka["priyankag Site"]:::static
    Yash["yash Site"]:::static
  end
  Browser -->|loads| Jainam
  Browser -->|loads| Praneeth
  Browser -->|loads| Akshay
  Browser -->|loads| Lorenh
  Browser -->|loads| Priyanka
  Browser -->|loads| Yash

  %% Firebase Auth Example
  subgraph "Firebase Auth Example"
    direction TB
    FirebaseAuth["Firebase Auth"]:::external
    RevanthApp["Flask App (revanth)"]:::compute
    AppYaml["app.yaml"]:::data
    FirebaseJson["firebase.json"]:::data
    ReqTxt["requirements.txt"]:::data
    Templates["HTML Templates"]:::static
  end
  Browser -->|auth| FirebaseAuth
  FirebaseAuth -->|tokens| RevanthApp
  RevanthApp -->|config| AppYaml
  RevanthApp -->|deploy config| FirebaseJson
  RevanthApp -->|deps| ReqTxt
  RevanthApp -->|renders| Templates

  %% Click Events
  click app.py "https://github.com/modelearth/cloud/blob/main/run/app.py"
  click app_local.py "https://github.com/modelearth/cloud/blob/main/run/app_local.py"
  click app_minimal.py "https://github.com/modelearth/cloud/blob/main/run/app_minimal.py"
  click app_unified.py "https://github.com/modelearth/cloud/blob/main/run/app_unified.py"
  click CoreRoutes "https://github.com/modelearth/cloud/blob/main/run/routes/core_routes.py"
  click NotebookRoutes "https://github.com/modelearth/cloud/blob/main/run/routes/notebook_runner.py"
  click NotebookUtils "https://github.com/modelearth/cloud/blob/main/run/utils/notebook_utils.py"
  click AuthUtils "https://github.com/modelearth/cloud/blob/main/run/utils/auth_utils.py"
  click ConfigUtils "https://github.com/modelearth/cloud/blob/main/run/utils/config_utils.py"
  click GitHubUtils "https://github.com/modelearth/cloud/blob/main/run/utils/github_utils.py"
  click CompatUtils "https://github.com/modelearth/cloud/blob/main/run/utils/compat_utils.py"
  click Dockerfile "https://github.com/modelearth/cloud/tree/main/run/Dockerfile"
  click DeploySh "https://github.com/modelearth/cloud/blob/main/run/deploy.sh"
  click RotateToken "https://github.com/modelearth/cloud/blob/main/run/rotate-token.sh"
  click FixImports "https://github.com/modelearth/cloud/blob/main/run/fix_imports.py"
  click GcloudIgnore "https://github.com/modelearth/cloud/blob/main/run/.gcloudignore"
  click DockerIgnore "https://github.com/modelearth/cloud/blob/main/run/.dockerignore"
  click ConfigYAML "https://github.com/modelearth/cloud/blob/main/run/config.yaml"
  click EnvFile "https://github.com/modelearth/cloud/blob/main/run/.env.example"
  click StaticAssets "https://github.com/modelearth/cloud/blob/main/run/index.html"
  click StaticAssets "https://github.com/modelearth/cloud/blob/main/run/js/param-input.js"
  click StaticAssets "https://github.com/modelearth/cloud/blob/main/run/page.html"
  click Notebooks "https://github.com/modelearth/cloud/blob/main/run/notebook.ipynb"
  click Notebooks "https://github.com/modelearth/cloud/blob/main/run/Run-Models-bkup.ipynb"
  click Notebooks "https://github.com/modelearth/cloud/blob/main/run/archived-notebook.ipynb"
  click Jainam "https://github.com/modelearth/cloud/blob/main/team/2025/Jainam/Index.html"
  click Praneeth "https://github.com/modelearth/cloud/blob/main/team/2025/Praneeth/index.html"
  click Akshay "https://github.com/modelearth/cloud/blob/main/team/2025/akshay/index.html"
  click Lorenh "https://github.com/modelearth/cloud/blob/main/team/2025/lorenh/index.html"
  click Priyanka "https://github.com/modelearth/cloud/blob/main/team/2025/priyankag/index.html"
  click Yash "https://github.com/modelearth/cloud/blob/main/team/2025/yash/index.html"
  click RevanthApp "https://github.com/modelearth/cloud/blob/main/team/2025/revanth/app.py"
  click FirebaseJson "https://github.com/modelearth/cloud/blob/main/team/2025/revanth/firebase.json"
  click AppYaml "https://github.com/modelearth/cloud/blob/main/team/2025/revanth/app.yaml"
  click ReqTxt "https://github.com/modelearth/cloud/blob/main/team/2025/revanth/requirements.txt"
  click Templates "https://github.com/modelearth/cloud/blob/main/team/2025/revanth/templates/index.html"

  %% Styles
  classDef compute fill:#ADD8E6,stroke:#000,stroke-width:1px
  classDef data fill:#90EE90,stroke:#000,stroke-width:1px
  classDef static fill:#D3D3D3,stroke:#000,stroke-width:1px
  classDef pipeline fill:#FFA500,stroke:#000,stroke-width:1px
  classDef external fill:#F9F871,stroke:#000,stroke-width:1px
```
