# abhinavsivanandhan/cloud architecture

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

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

## Overview

##### Project type and purpose
- This “cloud” repo is essentially a full‐stack, Flask‐based web application template and sample deployment for Google Cloud Run.
- It also contains:
- A “cloud-main” experimental Flask prototype (cloud-main/flask).
- A “run” directory with a working Flask service, Dockerfile, GCP configuration, notebooks, front-end assets and utility modules.
- A “team/2025” folder for static site / Firebase demos per contributor.

##### File structure
Top level
- README.md – project overview and links
- index.html – static landing page
- cloud-main/ – previous Flask experiment
- run/ – primary Cloud Run Flask service
– Dockerfile, deploy.sh, config.yaml, .env example, .gcloudignore
– app.py variants (local, minimal, unified)
– routes/ (core_routes.py, notebook_runner.py)
– utils/ (compat, config, GitHub, notebook utilities)
– js/ (parameter-input front-end logic)
– notebooks and archived ipynb demos
- team/2025/ – per‐user folders for GitHub Page demos and Firebase + Flask Auth sample

##### Key README insights
- Contributors fork this repo, add a folder under team/2025, deploy to GitHub Pages (static) or Firebase (dynamic via Flask).
- The stack uses Python/Flask, Docker, Google Cloud Run, optional Firebase Auth, static pages on GitHub Pages.

##### Main components
A. Front-end browsers / clients
– Static pages (index.html, page.html) and JS (param-input.js) served by Flask or GitHub Pages
B. Flask Application (Google Cloud Run)
– HTTP Server / WSGI entrypoint (app.py)
– Routing layer (core_routes.py, notebook_runner.py)
– Notebook execution engine (invokes notebook_utils)
– Business logic & external integrations (github_utils, config_utils)
C. Build & Deployment pipeline
– Docker build (Dockerfile) → Container Registry → Cloud Run service
– Deploy scripts (deploy.sh, gcloudignore, config.yaml)
D. Configuration & Secrets
– .env file / environment variables
– config.yaml / settings.local.json for Claude or GCP
E. Data & External Services
– GitHub API (via github_utils)
– Google Cloud services (Cloud Run, optionally Cloud Storage or Firestore if added later)
– Firebase Auth (in team/2025/revanth example)
F. Team / GitHub Pages
– Separate static sites under team/2025/[handle]
– Optional Firebase-backed Flask Auth example

##### Relationships & interactions
1. User’s Browser → HTTP(S) → Cloud Run (Flask service)
- GET/POST to /, /run-notebook, /api/*
2. Flask Controllers → Utility modules → execute Jupyter notebooks or call GitHub API
3. Flask Service ↔ Google Cloud Run Exec Environment (container)
4. CI/CD / deploy.sh → Docker → Cloud Build → Cloud Run
5. Contributors’ GitHub Pages → Static assets served directly

##### Architectural patterns & design principles
- MVC-style separation:
- “routes/” = Controllers
- “utils/” = Services
- “app.py” = Application entrypoint/config
- Containerization: single Docker image running Flask
- Infrastructure as code: config.yaml, deploy.sh
- Extensibility: per-user subfolders under team/2025 can be mounted on the same domain or served separately

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    Browser["User Browser"]:::client
    Browser -->|"HTTP GET/POST"| FlaskService["Flask App (Cloud Run)"]:::service
    Browser -->|"GET index.html"| LandingPage["Static Landing Page"]:::static
    Browser -->|"Loads JS"| ParamInput["Param Input JS"]:::static
    Browser -->|"Access Team Pages"| GitHubPages["GitHub Pages (team/2025)"]:::static
    Browser -->|"OAuth flow"| FirebaseDemo["Firebase Auth Demo"]:::external

    %% Static Assets
    LandingPage -->|"serves"| index_html
    ParamInput -->|"loaded from"| param_input_js

    %% Flask Service Subgraph
    subgraph "Flask App (Container)" 
        direction TB
        AppEntrypoint["app.py (Unified Entrypoint)"]:::service
        AppLocal["app_local.py"]:::service
        AppMinimal["app_minimal.py"]:::service
        CoreRoutes["core_routes.py"]:::controller
        NotebookRunner["notebook_runner.py"]:::controller
        AppEntrypoint -->|"routes to"| CoreRoutes
        AppEntrypoint -->|"routes to"| NotebookRunner
        CoreRoutes -->|"calls"| GitHubUtils
        NotebookRunner -->|"invokes"| NotebookUtils
    end

    %% Utilities Subgraph
    subgraph "Utility Modules" 
        direction TB
        NotebookUtils["notebook_utils.py"]:::util
        GitHubUtils["github_utils.py"]:::util
        ConfigUtils["config_utils.py"]:::util
        CompatUtils["compat_utils.py"]:::util
    end

    %% External Services
    GitHubAPI["GitHub API"]:::external
    GoogleCloudRun["Google Cloud Run"]:::external
    FirebaseAuth["Firebase Auth"]:::external

    FlaskService -->|"exec in container"| GoogleCloudRun
    Prompts -->|"uses API"| GitHubAPI
    FirebaseDemo -->|"Auth via"| FirebaseAuth

    NotebookUtils --> GitHubAPI

    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline" 
        direction TB
        Dockerfile["Dockerfile"]:::pipeline
        DeployScript["deploy.sh"]:::pipeline
        ConfigYaml["config.yaml"]:::pipeline
        Gcloudignore[".gcloudignore"]:::pipeline
        EnvExample[".env.example"]:::pipeline
        ClaudeConfig["settings.local.json"]:::pipeline
        Dockerfile -->|"build image"| ContainerRegistry["Container Registry"]:::external
        DeployScript -->|"deploy to"| CloudBuild["Cloud Build"]:::pipeline
        CloudBuild -->|"deploy to"| GoogleCloudRun
    end

    %% Team / Firebase Demo
    subgraph "Team/2025 - Revanth Demo"
        direction TB
        RevanthApp["app.py"]:::service
        FirebaseConfig["firebase.json & app.yaml"]:::pipeline
        Templates["templates/*"]:::static
        RevanthApp --> FirebaseAuth
    end

    %% Click Events
    click index_html "https://github.com/abhinavsivanandhan/cloud/blob/main/index.html"
    click param_input_js "https://github.com/abhinavsivanandhan/cloud/blob/main/run/js/param-input.js"
    click AppEntrypoint "https://github.com/abhinavsivanandhan/cloud/blob/main/run/app_unified.py"
    click AppLocal "https://github.com/abhinavsivanandhan/cloud/blob/main/run/app_local.py"
    click AppMinimal "https://github.com/abhinavsivanandhan/cloud/blob/main/run/app_minimal.py"
    click CoreRoutes "https://github.com/abhinavsivanandhan/cloud/blob/main/run/routes/core_routes.py"
    click NotebookRunner "https://github.com/abhinavsivanandhan/cloud/blob/main/run/routes/notebook_runner.py"
    click NotebookUtils "https://github.com/abhinavsivanandhan/cloud/blob/main/run/utils/notebook_utils.py"
    click GitHubUtils "https://github.com/abhinavsivanandhan/cloud/blob/main/run/utils/github_utils.py"
    click ConfigUtils "https://github.com/abhinavsivanandhan/cloud/blob/main/run/utils/config_utils.py"
    click CompatUtils "https://github.com/abhinavsivanandhan/cloud/blob/main/run/utils/compat_utils.py"
    click Dockerfile "https://github.com/abhinavsivanandhan/cloud/tree/main/run/Dockerfile"
    click DeployScript "https://github.com/abhinavsivanandhan/cloud/blob/main/run/deploy.sh"
    click ConfigYaml "https://github.com/abhinavsivanandhan/cloud/blob/main/run/config.yaml"
    click Gcloudignore "https://github.com/abhinavsivanandhan/cloud/blob/main/run/.gcloudignore"
    click EnvExample "https://github.com/abhinavsivanandhan/cloud/blob/main/run/.env.example"
    click ClaudeConfig "https://github.com/abhinavsivanandhan/cloud/blob/main/run/.claude/settings.local.json"
    click GitHubPages "https://github.com/abhinavsivanandhan/cloud/blob/main/team/2025/*/index.html"
    click RevanthApp "https://github.com/abhinavsivanandhan/cloud/blob/main/team/2025/revanth/app.py"

    %% Styles
    classDef client fill:#FFD27F,stroke:#E07B39,color:#000
    classDef service fill:#A4C2F4,stroke:#1155CC,color:#000
    classDef util fill:#D5A6BD,stroke:#741B47,color:#000
    classDef controller fill:#93C47D,stroke:#38761D,color:#000
    classDef pipeline fill:#F4CCCC,stroke:#CC0000,color:#000
    classDef external fill:#FFE599,stroke:#B45F06,color:#000
    classDef static fill:#B6D7A8,stroke:#38761D,color:#000
```
