# google-marketing-solutions/giga architecture

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

- Interactive diagram: https://gitdiagram.com/google-marketing-solutions/giga
- Repository: https://github.com/google-marketing-solutions/giga

## Overview

##### Project type and purpose
- This is a Google Apps Script-based web application (“webApp.html” + server-side .js files) that plugs into a Google Sheets spreadsheet.
- Purpose: Collect input keywords in the sheet, call Google’s Vertex AI (Gemini) to cluster & analyze keyword data, then write insights and campaign recommendations back into the sheet or display them via a web UI.

##### File structure
- Top-level:
- README, LICENSE, CONTRIBUTING, .gitignore → meta/config
- assets/logo.png → branding
- src/ → all application code and configuration
- Inside src/:
- appscript.json → Apps Script project manifest (scopes, web app settings)
- webApp.html → HTML/CSS/JS client served to user
- main.js → entry points and UI-to-server dispatch
- prompt.js → prompt construction logic for Vertex AI
- vertex.js → wrappers around Vertex AI API calls
- ideas.js, geo.js → domain logic: keyword idea retrieval, geo-specific clustering
- util.js → shared helper functions

##### Extract key insights from README
- Architecture implied:
User interacts via Google Sheets + embedded web app → Apps Script backend → calls Vertex AI → processes & writes back
- Dependencies: Google Workspace (Sheets), Google Cloud (Vertex AI), Google Ads (developer token)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Google-hosted services
    Sheets["Google Sheets UI"]:::googleHost
    VertexAI["Google Vertex AI"]:::googleHost
    AdsAPI["Google Ads API"]:::optional

    %% Apps Script Web App
    subgraph "Apps Script Web App"
        direction TB
        Manifest["appscript.json\n(App Manifest)"]:::config
        subgraph "UI Layer"
            direction TB
            WebUI["webApp.html\n(UI Layer)"]:::ui
        end
        subgraph "Logic Layer"
            direction TB
            Main["main.js\n(Client Entry & Dispatch)"]:::apps
            Ideas["ideas.js\n(Keyword Ideas Logic)"]:::apps
            Geo["geo.js\n(Geo-specific Clustering)"]:::apps
            Util["util.js\n(Shared Helpers)"]:::apps
        end
        subgraph "API Layer"
            direction TB
            Prompt["prompt.js\n(Prompt Construction)"]:::apps
            VertexClient["vertex.js\n(Vertex AI Client)"]:::apps
        end
    end

    %% Data flows
    Sheets -->|"opens Web App"| WebUI
    WebUI -->|"calls server"| Main
    Main -->|"builds prompt"| Prompt
    Prompt --> VertexClient
    Main -->|"optional fetch ideas"| Ideas
    Main -->|"optional geo cluster"| Geo
    VertexClient -->|"calls AI API"| VertexAI
    VertexAI -->|"returns insights"| VertexClient
    VertexClient --> Main
    Main -->|"writes results"| Sheets
    Main -->|"optional ADS call"| AdsAPI
    AdsAPI -->|"returns keyword ideas"| Main

    %% Click Events
    click Manifest "https://github.com/google-marketing-solutions/giga/blob/main/src/appscript.json"
    click WebUI "https://github.com/google-marketing-solutions/giga/blob/main/src/webApp.html"
    click Main "https://github.com/google-marketing-solutions/giga/blob/main/src/main.js"
    click Prompt "https://github.com/google-marketing-solutions/giga/blob/main/src/prompt.js"
    click VertexClient "https://github.com/google-marketing-solutions/giga/blob/main/src/vertex.js"
    click Ideas "https://github.com/google-marketing-solutions/giga/blob/main/src/ideas.js"
    click Geo "https://github.com/google-marketing-solutions/giga/blob/main/src/geo.js"
    click Util "https://github.com/google-marketing-solutions/giga/blob/main/src/util.js"

    %% Styles
    classDef googleHost fill:#9f6,stroke:#484,stroke-width:2px
    classDef apps fill:#6cf,stroke:#159,stroke-width:2px
    classDef ui fill:#f96,stroke:#c63,stroke-width:2px
    classDef config fill:#6cf,stroke:#159,stroke-width:2px,stroke-dasharray: 5 5
    classDef optional fill:#fff,stroke:#f90,stroke-width:2px,stroke-dasharray: 5 5
```
