# googlecloudplatform/vertex-ai-creative-studio architecture

> Architecture diagram of the GitHub repository googlecloudplatform/vertex-ai-creative-studio, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/googlecloudplatform/vertex-ai-creative-studio
- Repository: https://github.com/googlecloudplatform/vertex-ai-creative-studio

## Overview

##### Project Type and Purpose
- This is a full-stack, Python-based web application built on Mesop.
- It showcases Google Cloud Vertex AI generative APIs (Imagen for text-to-image, Gemini for prompts and multimodal critique).
- It's delivered as a monolithic Mesop app (root “main.py”) plus a collection of standalone “experiments” apps (Arena, Babel, Veo, etc.) in the same repo.

##### File Structure
Top-level:
- main.py – entry point for the Mesop web server
- config/ – application configuration (GCP project, storage bucket, credentials)
- models/ – Python modules calling Vertex AI models
- prompts/ – prompt templates, critic logic
- experiments/ – multiple subfolders; each experiment is a self-contained app or service
- requirements.txt, Procfile, env_template – deployment and environment setup

experiments/arena (example):
- components/, pages/, state/ – Mesop UI layers
- config/ – Firebase/Spanner configs
- scripts/ – data ingestion to Firestore, GCS bulk upload
- models/ – model-wrapping Python code

##### README for Insights
- The root README confirms:
– Uses Mesop for UI
– Requires PROJECT_ID + IMAGE_CREATION_BUCKET (GCS)
– Deployable on Cloud Run (Cloud Run service account with AI and Storage roles)
- Experiments are stand-alone demos awaiting integration into the main app.

##### Main Components
A. Mesop Web Application (Monolith)
– UI Layer (Pages, Components)
– Business Logic Layer (models/, prompts/)
– Config Layer (config/)
B. External Services
– Vertex AI APIs (Imagen, Gemini)
– Google Cloud Storage (bucket for generated media)
– (Optionally) Firestore or Spanner if used by experiments
C. Deployment Targets
– Local (Mesop CLI)
– Cloud Run (Container)

##### Relationships & Data Flows
- User → HTTP(S) → Mesop server (main.py)
- Mesop UI triggers business logic
- Business logic calls Vertex AI REST/gRPC endpoints
- AI responses return to Mesop, rendered in browser
- For images: Mesop uploads to GCS → GCS returns URL → displayed in UI
- (Experiments only) Ingestion scripts load metadata into Firestore/Spanner → Data shown in experiment UI

##### Architectural Patterns & Principles
- Monolithic UI + backend in one Python process
- Layered separation: UI Components → Business Logic (model wrappers) → External API/Storage
- Modular “experiments” folder: each demo is a self-contained micro-app
- Twelve-factor app conventions (env vars, Procfile, config directory)

##### Technologies & Frameworks to Highlight
- Mesop (Python UI framework)
- Python 3 modules (models/, prompts/, utils/)
- Vertex AI generative APIs (Imagen, Gemini)
- Google Cloud Storage
- (Experiments) Firestore/Spanner, Dockerfiles, Go services (Babel, MCP-GenMedia), Jupyter notebooks

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "User & Deployment"
        direction TB
        User["User Browser"]:::ui
        Local["Local (Mesop CLI)"]:::infra
        CR["Cloud Run"]:::infra
    end

    subgraph "Root Monolith App"
        direction TB
        MS["Mesop Server"]:::backend
        CFG["Config Layer"]:::config
        UI_R["UI Layer (Pages & Components)"]:::ui
        BL1["Model Wrappers"]:::logic
        BL2["Prompt Templates & Critic Logic"]:::logic
        PF["Procfile"]:::infra
        ET["env_template"]:::infra
        RT["requirements.txt"]:::infra
    end

    subgraph "Experiments"
        direction TB

        subgraph "Arena"
            direction TB
            ARENA_UI["UI Components"]:::ui
            ARENA_PG["Pages"]:::ui
            ARENA_ST["State Management"]:::logic
            ARENA_CFG["Config (Firebase/Spanner)"]:::config
            ARENA_MDL["Model Wrappers"]:::logic
            ARENA_SC["Data Ingestion Scripts"]:::infra
            ARENA_PR["Prompt Templates"]:::logic
        end

        subgraph "Babel"
            direction TB
            BBL_UI["UI Components"]:::ui
            BBL_PG["Pages"]:::ui
            BBL_CFG["Config & Setup"]:::config
            BBL_COM["Common Utilities"]:::logic
            BBL_GO1["Go Service: main.go"]:::backend
            BBL_GO2["Go Service: speak.go"]:::backend
        end

        subgraph "Veo"
            direction TB
            VEO_UI["UI Components"]:::ui
            VEO_PG["Pages"]:::ui
            VEO_CFG["Config"]:::config
            VEO_MDL["Models (Gemini, Lyria, VEO)"]:::logic
            VEO_COM["Common Utilities & Storage"]:::logic
            VEO_ST["State Management"]:::logic
        end

        subgraph "MCP-GenMedia"
            direction TB
            subgraph "Go Microservices"
                direction TB
                MS_IM["Imagen Service"]:::backend
                MS_CH["Chirp3 Service"]:::backend
                MS_VE["VEO Service"]:::backend
                MS_LY["Lyria Service"]:::backend
                MS_AV["AVTool Service"]:::backend
            end
            subgraph "Sample Agents"
                direction TB
                AG_PY["Python ADK Agent"]:::logic
                AG_JS["GenKit JS Agent"]:::logic
            end
        end

        subgraph "Podcast Assistant Demo"
            direction TB
            CPI["Jupyter Notebook Demo"]:::external
        end
    end

    subgraph "External Services"
        direction TB
        VAI["Vertex AI (Imagen, Gemini)"]:::external
        GCS["Google Cloud Storage"]:::datastore
        FS["Firestore/Spanner"]:::datastore
    end

    %% Relationships
    User -->|HTTP| MS
    MS --> UI_R
    UI_R --> BL1
    UI_R --> BL2
    BL1 --> VAI
    BL2 --> VAI
    BL1 --> GCS
    MS --> GCS
    MS -->|deployed on| Local
    MS -->|deployed on| CR

    User --> ARENA_UI
    ARENA_UI --> ARENA_MDL
    ARENA_MDL --> VAI
    ARENA_SC --> FS
    ARENA_SC --> GCS

    User --> BBL_UI
    BBL_UI --> BBL_GO1
    BBL_UI --> BBL_GO2
    BBL_GO1 --> VAI
    BBL_GO2 --> VAI

    User --> VEO_UI
    VEO_UI --> VEO_MDL
    VEO_MDL --> VAI

    User --> CPI
    CPI --> VAI
    CPI --> GCS

    %% Click Events
    click MS "https://github.com/googlecloudplatform/vertex-ai-creative-studio/blob/main/main.py"
    click CFG "https://github.com/googlecloudplatform/vertex-ai-creative-studio/tree/main/config/"
    click BL1 "https://github.com/googlecloudplatform/vertex-ai-creative-studio/tree/main/models/"
    click BL2 "https://github.com/googlecloudplatform/vertex-ai-creative-studio/tree/main/prompts/"
    click PF "https://github.com/googlecloudplatform/vertex-ai-creative-studio/tree/main/Procfile"
    click ET "https://github.com/googlecloudplatform/vertex-ai-creative-studio/tree/main/env_template"
    click RT "https://github.com/googlecloudplatform/vertex-ai-creative-studio/blob/main/requirements.txt"
    click ARENA_UI "https://github.com/googlecloudplatform/vertex-ai-creative-studio/tree/main/experiments/arena/components/"
    click ARENA_PG "https://github.com/googlecloudplatform/vertex-ai-creative-studio/tree/main/experiments/arena/pages/"
    click ARENA_ST "https://github.com/googlecloudplatform/vertex-ai-creative-studio/tree/main/experiments/arena/state/"
    click ARENA_CFG "https://github.com/googlecloudplatform/vertex-ai-creative-studio/tree/main/experiments/arena/config/"
    click ARENA_MDL "https://github.com/googlecloudplatform/vertex-ai-creative-studio/tree/main/experiments/arena/models/"
    click ARENA_SC "https://github.com/googlecloudplatform/vertex-ai-creative-studio/tree/main/experiments/arena/scripts/"
    click ARENA_PR "https://github.com/googlecloudplatform/vertex-ai-creative-studio/tree/main/experiments/arena/prompts/"
    click BBL_UI "https://github.com/googlecloudplatform/vertex-ai-creative-studio/tree/main/experiments/babel/app/components/"
    click BBL_PG "https://github.com/googlecloudplatform/vertex-ai-creative-studio/tree/main/experiments/babel/app/pages/"
    click BBL_CFG "https://github.com/googlecloudplatform/vertex-ai-creative-studio/tree/main/experiments/babel/app/config/"
    click BBL_CFG "https://github.com/googlecloudplatform/vertex-ai-creative-studio/tree/main/experiments/babel/app/set_up/"
    click BBL_COM "https://github.com/googlecloudplatform/vertex-ai-creative-studio/tree/main/experiments/babel/app/common/"
    click BBL_GO1 "https://github.com/googlecloudplatform/vertex-ai-creative-studio/blob/main/experiments/babel/main.go"
    click BBL_GO2 "https://github.com/googlecloudplatform/vertex-ai-creative-studio/blob/main/experiments/babel/speak.go"
    click VEO_UI "https://github.com/googlecloudplatform/vertex-ai-creative-studio/tree/main/experiments/veo-app/components/"
    click VEO_PG "https://github.com/googlecloudplatform/vertex-ai-creative-studio/tree/main/experiments/veo-app/pages/"
    click VEO_CFG "https://github.com/googlecloudplatform/vertex-ai-creative-studio/tree/main/experiments/veo-app/config/"
    click VEO_MDL "https://github.com/googlecloudplatform/vertex-ai-creative-studio/tree/main/experiments/veo-app/models/"
    click VEO_COM "https://github.com/googlecloudplatform/vertex-ai-creative-studio/tree/main/experiments/veo-app/common/"
    click VEO_ST "https://github.com/googlecloudplatform/vertex-ai-creative-studio/tree/main/experiments/veo-app/state/"
    click MS_IM "https://github.com/googlecloudplatform/vertex-ai-creative-studio/blob/main/experiments/mcp-genmedia/mcp-genmedia-go/mcp-imagen-go/imagen.go"
    click MS_CH "https://github.com/googlecloudplatform/vertex-ai-creative-studio/blob/main/experiments/mcp-genmedia/mcp-genmedia-go/mcp-chirp3-go/chirp3.go"
    click MS_VE "https://github.com/googlecloudplatform/vertex-ai-creative-studio/blob/main/experiments/mcp-genmedia/mcp-genmedia-go/mcp-veo-go/veo.go"
    click MS_LY "https://github.com/googlecloudplatform/vertex-ai-creative-studio/blob/main/experiments/mcp-genmedia/mcp-genmedia-go/mcp-lyria-go/lyria.go"
    click MS_AV "https://github.com/googlecloudplatform/vertex-ai-creative-studio/blob/main/experiments/mcp-genmedia/mcp-genmedia-go/mcp-avtool-go/avtool.go"
    click AG_PY "https://github.com/googlecloudplatform/vertex-ai-creative-studio/blob/main/experiments/mcp-genmedia/sample-agents/adk/genmedia_agent/agent.py"
    click AG_JS "https://github.com/googlecloudplatform/vertex-ai-creative-studio/blob/main/experiments/mcp-genmedia/sample-agents/genkit/genkit-agent-js/src/index.js"
    click CPI "https://github.com/googlecloudplatform/vertex-ai-creative-studio/blob/main/experiments/creative_podcast_assistant/NEXT_Demo_Speech_to_Text_and_Text_to_Speech_features.ipynb"

    %% Styles
    classDef ui fill:#B3D4FC,stroke:#0366D6,stroke-width:1px
    classDef backend fill:#CFF9C9,stroke:#2C662D,stroke-width:1px
    classDef logic fill:#D4F1BE,stroke:#5A8F29,stroke-width:1px
    classDef config fill:#FFE4B5,stroke:#DAA520,stroke-width:1px
    classDef infra fill:#E0BBE4,stroke:#8860A8,stroke-width:1px
    classDef external fill:#FFD2D2,stroke:#D43D3D,stroke-width:1px
    classDef datastore fill:#FFF5BA,stroke:#D4A017,stroke-width:1px
```
