# googlecloudplatform/generative-ai architecture

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

- Interactive diagram: https://gitdiagram.com/googlecloudplatform/generative-ai
- Repository: https://github.com/googlecloudplatform/generative-ai

## Overview

#### Purpose and Repository Shape
This is a curated Google Cloud generative-AI sample repository, not one deployable product. It combines notebooks, reference implementations, sample applications, and infrastructure examples for Gemini, Agent Platform, Search, audio, vision, embeddings, and open/partner models. Root navigation is `README.md`; topic-level entry points include `gemini/README.md`, `search/README.md`, and `setup-env/README.md`.

#### Primary Consumption Paths
Most assets are independently runnable notebooks or self-contained samples; there is no shared application runtime or monorepo build entry point. Users typically begin with API/model notebooks under `gemini/getting-started/`, service-specific examples under `agents/`, `search/`, `audio/`, and `vision/`, or deployable sample directories containing their own dependency and container manifests. Representative entry points: `gemini/getting-started/intro_gemini_3_6_flash.ipynb`, `agents/adk/new-hire-onboarding/app/agent.py`, `search/web-app/main.py`.

#### Gemini and Agent Workflows
`gemini/` is the largest capability area: model invocation, function calling, MCP, evaluation, RAG, tuning, multimodal live APIs, and end-to-end apps. Agent examples span ADK and Agent Engine, often exposing Python/FastAPI services, state schemas, tools, telemetry, and optional browser UIs. Key examples include `agents/adk/contract-compliance-pipeline/python-extraction-agent/app/fast_api_app.py`, `agents/adk/contract-compliance-pipeline/python-extraction-agent/app/agent.py`, and `gemini/mcp/adk_multiagent_mcp_app/main.py`.

#### Application Architecture Examples
Several directories are complete but independent vertical slices, useful as reference architectures rather than shared platform components. Typical boundaries are frontend/UI → HTTP or WebSocket backend → model/agent orchestration → external data/tools. For example, the LangGraph concierge separates graph nodes and FastAPI serving in `gemini/agents/genai-experience-concierge/langgraph-demo/backend/concierge/langgraph_server/fastapi_app.py` and `gemini/agents/genai-experience-concierge/langgraph-demo/backend/concierge/nodes/`; its separate UI is under `gemini/agents/genai-experience-concierge/langgraph-demo/frontend/concierge_ui/`.

#### Retrieval, Search, and Data Boundaries
Search and RAG samples demonstrate ingestion/indexing, retrieval, reranking, grounding, evaluation, and answer generation. They interface with managed Google services rather than a repository-wide storage layer. The LlamaIndex RAG sample separates indexing from query serving in `gemini/sample-apps/llamaindex-rag/backend/indexing/run_parse_embed_index.py` and `gemini/sample-apps/llamaindex-rag/backend/app/routers/rag.py`. Agent Search examples provide web and Cloud Function integration in `search/web-app/main.py` and `search/cloud-function/python/vertex_ai_search_client.py`.

#### Runtimes and Infrastructure
Material runtimes are Python (notebooks, FastAPI, Flask/Streamlit-style apps), JavaScript/TypeScript (React, Angular, Vite, browser media clients), and Go (some service/job samples). Deployable samples commonly include Dockerfiles; selected systems add Docker Compose, Cloud Build, Terraform, Cloud Run, GKE, App Engine, or Cloud Functions. Infrastructure boundaries are explicit in `gemini/agents/genai-experience-concierge/langgraph-demo/terraform/`, `agents/adk/contract-compliance-pipeline/docker-compose.yml`, and `gemini/multimodal-live-api/project-livewire/server/Dockerfile`.

#### External Services and Integration Surfaces
Examples target Google Cloud Generative AI/Gemini and Vertex AI services, including Agent Platform/Agent Engine, Gemini Enterprise/Agent Search, Vector Search, BigQuery, Cloud Storage, Document AI, and model-serving infrastructure. Some samples integrate protocol or real-time systems such as MCP, A2A, WebSockets, LiveKit, and browser audio worklets. Concrete integration surfaces include `gemini/multimodal-live-api/livekit-adk/app/livekit_bridge.py`, `search/gemini-enterprise/group-licensing/internal/adapters/`, and `gemini/use-cases/applying-llms-to-data/using-gemini-with-bigquery-remote-functions/`.

Main entry points: [`README.md`](https://github.com/googlecloudplatform/generative-ai/blob/main/README.md) (Root catalog), [`gemini/README.md`](https://github.com/googlecloudplatform/generative-ai/blob/main/gemini/README.md) (Gemini catalog), [`gemini/agents/genai-experience-concierge/langgraph-demo/backend/concierge/langgraph_server/fastapi_app.py`](https://github.com/googlecloudplatform/generative-ai/blob/main/gemini/agents/genai-experience-concierge/langgraph-demo/backend/concierge/langgraph_server/fastapi_app.py) (Concierge API), [`gemini/sample-apps/llamaindex-rag/backend/app/routers/rag.py`](https://github.com/googlecloudplatform/generative-ai/blob/main/gemini/sample-apps/llamaindex-rag/backend/app/routers/rag.py) (RAG query API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_navigation["Repository navigation"]
  node_root_readme["Root catalog<br/>documentation<br/>[README.md]"]
  node_gemini_readme["Gemini catalog<br/>topic guide<br/>[README.md]"]
  node_search_readme["Search catalog<br/>topic guide<br/>[README.md]"]
  node_setup_readme["Environment setup<br/>setup guide<br/>[README.md]"]
end

subgraph group_capabilities["Capability samples"]
  node_gemini_notebook["Gemini intro notebook"]
  node_mcp_multiagent["MCP multi-agent app<br/>Python app<br/>[main.py]"]
  node_livekit_bridge["LiveKit bridge<br/>real-time integration<br/>[livekit_bridge.py]"]
end

subgraph group_agent_apps["Agent reference apps"]
  node_adk_onboarding["ADK onboarding agent<br/>Python agent<br/>[agent.py]"]
  node_contract_api["Contract API<br/>FastAPI service<br/>[fast_api_app.py]"]
  node_contract_agent{{"Contract extraction agent<br/>ADK agent<br/>[agent.py]"}}
  node_concierge_ui["Concierge UI<br/>browser UI"]
  node_concierge_api["Concierge API<br/>FastAPI service<br/>[fastapi_app.py]"]
  node_concierge_nodes{{"Concierge graph nodes<br/>LangGraph workflow"}}
end

subgraph group_retrieval["Search and RAG"]
  node_rag_indexing["RAG indexing pipeline<br/>indexing job"]
  node_rag_router["RAG query API<br/>API router<br/>[rag.py]"]
  node_search_web_app["Agent Search web app<br/>Python web app<br/>[main.py]"]
  node_search_function_client["Search Cloud Function client<br/>Python integration"]
end

subgraph group_deployment["Deployment examples"]
  node_concierge_terraform["Concierge Terraform<br/>infrastructure"]
  node_contract_compose["Contract Compose<br/>container orchestration<br/>[docker-compose.yml]"]
  node_livewire_docker["Livewire server image<br/>Docker image"]
end

node_google_ai[("Google AI services<br/>external managed services")]

node_root_readme -->|"links to"| node_gemini_readme
node_root_readme -->|"links to"| node_search_readme
node_root_readme -->|"links to"| node_setup_readme
node_gemini_readme -->|"guides users to"| node_gemini_notebook
node_gemini_readme -->|"includes"| node_mcp_multiagent
node_mcp_multiagent -->|"invokes"| node_google_ai
node_adk_onboarding -->|"uses"| node_google_ai
node_contract_api -->|"serves"| node_contract_agent
node_contract_agent -->|"orchestrates via"| node_google_ai
node_contract_compose -->|"runs"| node_contract_api
node_concierge_ui -->|"HTTP requests"| node_concierge_api
node_concierge_api -->|"executes"| node_concierge_nodes
node_concierge_nodes -->|"invokes"| node_google_ai
node_concierge_terraform -.->|"provisions deployment for"| node_concierge_api
node_rag_indexing -->|"creates managed index via"| node_google_ai
node_rag_router -->|"queries index built by"| node_rag_indexing
node_rag_router -->|"retrieves and generates via"| node_google_ai
node_search_readme -->|"guides users to"| node_search_web_app
node_search_web_app -.->|"can integrate through"| node_search_function_client
node_search_function_client -->|"calls Agent Search"| node_google_ai
node_livekit_bridge -->|"connects live agent to"| node_google_ai
node_livewire_docker -.->|"represents deployable real-time pattern"| node_livekit_bridge

click node_root_readme "https://github.com/googlecloudplatform/generative-ai/blob/main/README.md"
click node_gemini_readme "https://github.com/googlecloudplatform/generative-ai/blob/main/gemini/README.md"
click node_search_readme "https://github.com/googlecloudplatform/generative-ai/blob/main/search/README.md"
click node_setup_readme "https://github.com/googlecloudplatform/generative-ai/blob/main/setup-env/README.md"
click node_gemini_notebook "https://github.com/googlecloudplatform/generative-ai/blob/main/gemini/getting-started/intro_gemini_3_6_flash.ipynb"
click node_mcp_multiagent "https://github.com/googlecloudplatform/generative-ai/blob/main/gemini/mcp/adk_multiagent_mcp_app/main.py"
click node_adk_onboarding "https://github.com/googlecloudplatform/generative-ai/blob/main/agents/adk/new-hire-onboarding/app/agent.py"
click node_contract_api "https://github.com/googlecloudplatform/generative-ai/blob/main/agents/adk/contract-compliance-pipeline/python-extraction-agent/app/fast_api_app.py"
click node_contract_agent "https://github.com/googlecloudplatform/generative-ai/blob/main/agents/adk/contract-compliance-pipeline/python-extraction-agent/app/agent.py"
click node_concierge_api "https://github.com/googlecloudplatform/generative-ai/blob/main/gemini/agents/genai-experience-concierge/langgraph-demo/backend/concierge/langgraph_server/fastapi_app.py"
click node_rag_indexing "https://github.com/googlecloudplatform/generative-ai/blob/main/gemini/sample-apps/llamaindex-rag/backend/indexing/run_parse_embed_index.py"
click node_rag_router "https://github.com/googlecloudplatform/generative-ai/blob/main/gemini/sample-apps/llamaindex-rag/backend/app/routers/rag.py"
click node_search_web_app "https://github.com/googlecloudplatform/generative-ai/blob/main/search/web-app/main.py"
click node_search_function_client "https://github.com/googlecloudplatform/generative-ai/blob/main/search/cloud-function/python/vertex_ai_search_client.py"
click node_livekit_bridge "https://github.com/googlecloudplatform/generative-ai/blob/main/gemini/multimodal-live-api/livekit-adk/app/livekit_bridge.py"
click node_contract_compose "https://github.com/googlecloudplatform/generative-ai/blob/main/agents/adk/contract-compliance-pipeline/docker-compose.yml"
click node_livewire_docker "https://github.com/googlecloudplatform/generative-ai/blob/main/gemini/multimodal-live-api/project-livewire/server/Dockerfile"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_root_readme,node_gemini_readme,node_search_readme,node_setup_readme toneBlue
class node_gemini_notebook,node_mcp_multiagent,node_livekit_bridge toneAmber
class node_adk_onboarding,node_contract_api,node_contract_agent,node_concierge_ui,node_concierge_api,node_concierge_nodes toneMint
class node_rag_indexing,node_rag_router,node_search_web_app,node_search_function_client toneRose
class node_concierge_terraform,node_contract_compose,node_livewire_docker toneIndigo
class node_google_ai toneNeutral
```

## Components

### Repository navigation

Curated entry points organize independent samples.

- [Root catalog](https://github.com/googlecloudplatform/generative-ai/blob/main/README.md): documentation · Repository-wide navigation for the sample collection. · `README.md`
- [Gemini catalog](https://github.com/googlecloudplatform/generative-ai/blob/main/gemini/README.md): topic guide · `gemini/README.md`
- [Search catalog](https://github.com/googlecloudplatform/generative-ai/blob/main/search/README.md): topic guide · `search/README.md`
- [Environment setup](https://github.com/googlecloudplatform/generative-ai/blob/main/setup-env/README.md): setup guide · `setup-env/README.md`

### Capability samples

Notebooks and examples grouped by AI capability.

- [Gemini intro notebook](https://github.com/googlecloudplatform/generative-ai/blob/main/gemini/getting-started/intro_gemini_3_6_flash.ipynb): notebook · Independently runnable model API learning path. · `gemini/getting-started/intro_gemini_3_6_flash.ipynb`
- [MCP multi-agent app](https://github.com/googlecloudplatform/generative-ai/blob/main/gemini/mcp/adk_multiagent_mcp_app/main.py): Python app · Agent orchestration example using MCP. · `gemini/mcp/adk_multiagent_mcp_app/main.py`
- [LiveKit bridge](https://github.com/googlecloudplatform/generative-ai/blob/main/gemini/multimodal-live-api/livekit-adk/app/livekit_bridge.py): real-time integration · Connects a live agent flow to LiveKit. · `gemini/multimodal-live-api/livekit-adk/app/livekit_bridge.py`

### Agent reference apps

Independent agent architectures and service layers.

- [ADK onboarding agent](https://github.com/googlecloudplatform/generative-ai/blob/main/agents/adk/new-hire-onboarding/app/agent.py): Python agent · `agents/adk/new-hire-onboarding/app/agent.py`
- [Contract API](https://github.com/googlecloudplatform/generative-ai/blob/main/agents/adk/contract-compliance-pipeline/python-extraction-agent/app/fast_api_app.py): FastAPI service · HTTP boundary for the extraction-agent sample. · `agents/adk/contract-compliance-pipeline/python-extraction-agent/app/fast_api_app.py`
- [Contract extraction agent](https://github.com/googlecloudplatform/generative-ai/blob/main/agents/adk/contract-compliance-pipeline/python-extraction-agent/app/agent.py): ADK agent · `agents/adk/contract-compliance-pipeline/python-extraction-agent/app/agent.py`
- **Concierge UI**: browser UI
- [Concierge API](https://github.com/googlecloudplatform/generative-ai/blob/main/gemini/agents/genai-experience-concierge/langgraph-demo/backend/concierge/langgraph_server/fastapi_app.py): FastAPI service · Serving boundary for the LangGraph concierge. · `gemini/agents/genai-experience-concierge/langgraph-demo/backend/concierge/langgraph_server/fastapi_app.py`
- **Concierge graph nodes**: LangGraph workflow · Orchestration nodes behind the API.

### Search and RAG

Indexing, retrieval, and managed search integrations.

- [RAG indexing pipeline](https://github.com/googlecloudplatform/generative-ai/blob/main/gemini/sample-apps/llamaindex-rag/backend/indexing/run_parse_embed_index.py): indexing job · Parses, embeds, and indexes source content. · `gemini/sample-apps/llamaindex-rag/backend/indexing/run_parse_embed_index.py`
- [RAG query API](https://github.com/googlecloudplatform/generative-ai/blob/main/gemini/sample-apps/llamaindex-rag/backend/app/routers/rag.py): API router · Query-serving boundary for the LlamaIndex sample. · `gemini/sample-apps/llamaindex-rag/backend/app/routers/rag.py`
- [Agent Search web app](https://github.com/googlecloudplatform/generative-ai/blob/main/search/web-app/main.py): Python web app · `search/web-app/main.py`
- [Search Cloud Function client](https://github.com/googlecloudplatform/generative-ai/blob/main/search/cloud-function/python/vertex_ai_search_client.py): Python integration · `search/cloud-function/python/vertex_ai_search_client.py`

### Deployment examples

Per-sample container and infrastructure boundaries.

- **Concierge Terraform**: infrastructure
- [Contract Compose](https://github.com/googlecloudplatform/generative-ai/blob/main/agents/adk/contract-compliance-pipeline/docker-compose.yml): container orchestration · `agents/adk/contract-compliance-pipeline/docker-compose.yml`
- [Livewire server image](https://github.com/googlecloudplatform/generative-ai/blob/main/gemini/multimodal-live-api/project-livewire/server/Dockerfile): Docker image · `gemini/multimodal-live-api/project-livewire/server/Dockerfile`

### Other components

- **Google AI services**: external managed services · Gemini, Vertex AI, Agent Platform, and related managed APIs.

## Connections

- Root catalog → Gemini catalog: links to
- Root catalog → Search catalog: links to
- Root catalog → Environment setup: links to
- Gemini catalog → Gemini intro notebook: guides users to
- Gemini catalog → MCP multi-agent app: includes
- MCP multi-agent app → Google AI services: invokes
- ADK onboarding agent → Google AI services: uses
- Contract API → Contract extraction agent: serves
- Contract extraction agent → Google AI services: orchestrates via
- Contract Compose → Contract API: runs
- Concierge UI → Concierge API: HTTP requests
- Concierge API → Concierge graph nodes: executes
- Concierge graph nodes → Google AI services: invokes
- Concierge Terraform → Concierge API: provisions deployment for
- RAG indexing pipeline → Google AI services: creates managed index via
- RAG query API → RAG indexing pipeline: queries index built by
- RAG query API → Google AI services: retrieves and generates via
- Search catalog → Agent Search web app: guides users to
- Agent Search web app → Search Cloud Function client: can integrate through
- Search Cloud Function client → Google AI services: calls Agent Search
- LiveKit bridge → Google AI services: connects live agent to
- Livewire server image → LiveKit bridge: represents deployable real-time pattern
