How modelearth/cloud works
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.