# googlecloudplatform/applied-ai-engineering-samples architecture

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

- Interactive diagram: https://gitdiagram.com/googlecloudplatform/applied-ai-engineering-samples
- Repository: https://github.com/googlecloudplatform/applied-ai-engineering-samples

## Overview

##### Project type and purpose
- This is a monorepo of reference blueprints, code samples, and hands-on labs for “Applied AI Engineering” on Google Cloud.
- It is divided into three main verticals:
- Generative AI on Vertex AI (“genai-on-vertex-ai”)
- AI/ML infrastructure best practices (“ai-infrastructure”)
- Research operationalization examples (“research-operationalization”)

##### File structure
- Top-level directories:
- .github, docs, assets – repository management & documentation.
- ai-infrastructure – Terraform modules and end-to-end environment definitions for provisioning GCP infra (GKE, TPU, Cloud Storage, etc.).
- genai-on-vertex-ai – notebooks, scripts, and sample apps demonstrating Vertex AI services: foundation models (Gemini), evaluation, RAG, search, agents, prompting recipes, “needle in a haystack” tool.
- research-operationalization – code and notebooks showing how to run research models (e.g., timesfm) on Vertex AI.
- Under ai-infrastructure:
- terraform-modules – reusable modules (bootstrap, gke-aiml, kueue-config, metrics-tracking, workload-identity).
- tpu-training-on-gke – step-by-step environment folder (0-bootstrap → 1-base-infrastructure → 2-gke-config) plus examples.
- Under genai-on-vertex-ai:
- gemini, vertex_evaluation_services, retrieval_augmented_generation, vertex_ai_search, agents, research prompts, each with its own notebooks, scripts, configs.
- Under research-operationalization:
- timesfm folder with a Jupyter notebook.

##### README for additional insights
- The root README declares the three pillars and links to each section’s README for deeper architecture descriptions.
- The ai-infrastructure README will describe the cloud architecture (Terraform → GCP resources).
- The genai README sections describe which Vertex AI services are exercised.

##### Detail
- Essential element: local developer, CI, Terraform, GCP infra, code workloads, Vertex AI services, storage.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Monorepo Root
    Repo["Monorepo Root\n(Applied AI Engineering Samples)"]:::repo

    %% CI and Docs
    Repo --> CI["Developer Workstation / CI"]:::ci
    click CI "https://github.com/googlecloudplatform/applied-ai-engineering-samples/blob/main/.github/workflows/pages-build-deployment.yml"
    Repo --> Docs["Documentation (MkDocs & Assets)"]:::doc
    click Docs "https://github.com/googlecloudplatform/applied-ai-engineering-samples/tree/main/docs/"

    CI --> Docs

    %% Infrastructure Provisioning
    Repo --> Infra["AI/ML Infrastructure Provisioning\n(Terraform)"]:::infra
    click Infra "https://github.com/googlecloudplatform/applied-ai-engineering-samples/blob/main/ai-infrastructure/README.md"

    subgraph "Terraform Modules" 
        direction TB
        BM["bootstrap"]:::infra
        GM["gke-aiml"]:::infra
        KM["kueue-config"]:::infra
        MM["metrics-tracking"]:::infra
        WM["workload-identity"]:::infra
        click BM "https://github.com/googlecloudplatform/applied-ai-engineering-samples/tree/main/ai-infrastructure/terraform-modules/bootstrap/"
        click GM "https://github.com/googlecloudplatform/applied-ai-engineering-samples/tree/main/ai-infrastructure/terraform-modules/gke-aiml/"
        click KM "https://github.com/googlecloudplatform/applied-ai-engineering-samples/tree/main/ai-infrastructure/terraform-modules/kueue-config/"
        click MM "https://github.com/googlecloudplatform/applied-ai-engineering-samples/tree/main/ai-infrastructure/terraform-modules/metrics-tracking/"
        click WM "https://github.com/googlecloudplatform/applied-ai-engineering-samples/tree/main/ai-infrastructure/terraform-modules/workload-identity/"
    end

    infra --> BM
    infra --> GM
    infra --> KM
    infra --> MM
    infra --> WM

    subgraph "TPU Training on GKE Environment" 
        direction TB
        S0["0-bootstrap"]:::infra
        S1["1-base-infrastructure"]:::infra
        S2["2-gke-config"]:::infra
        EX["examples & jobsets"]:::code
        IM["images"]:::code
        click S0 "https://github.com/googlecloudplatform/applied-ai-engineering-samples/tree/main/ai-infrastructure/tpu-training-on-gke/environment/0-bootstrap/"
        click S1 "https://github.com/googlecloudplatform/applied-ai-engineering-samples/tree/main/ai-infrastructure/tpu-training-on-gke/environment/1-base-infrastructure/"
        click S2 "https://github.com/googlecloudplatform/applied-ai-engineering-samples/tree/main/ai-infrastructure/tpu-training-on-gke/environment/2-gke-config/"
        click EX "https://github.com/googlecloudplatform/applied-ai-engineering-samples/tree/main/ai-infrastructure/tpu-training-on-gke/examples/"
        click IM "https://github.com/googlecloudplatform/applied-ai-engineering-samples/tree/main/ai-infrastructure/tpu-training-on-gke/images/"
    end

    infra --> S0
    infra --> S1
    infra --> S2
    infra --> EX
    infra --> IM

    %% GCP Resources
    infra --> GKE["GKE Cluster"]:::compute
    infra --> TPU["TPU Pod"]:::compute
    infra --> VPC["VPC"]:::service
    infra --> GCS["Cloud Storage"]:::datastore
    infra --> REG["Container Registry"]:::service
    infra --> BQ["BigQuery"]:::datastore

    %% Generative AI on Vertex AI
    Repo --> GenAI["Generative AI on Vertex AI"]:::code
    click GenAI "https://github.com/googlecloudplatform/applied-ai-engineering-samples/blob/main/genai-on-vertex-ai/README.md"

    subgraph "GenAI Samples" 
        direction TB
        GEM["Foundation Models\n(Gemini)"]:::code
        PR["Prompting Recipes"]:::code
        NH["Needle in a Haystack"]:::code
        RAG["Retrieval-Augmented Generation"]:::code
        SAS["Vertex AI Search"]:::code
        VES["Vertex Evaluation Services"]:::code
        AGT["Agents & Reasoning Engine"]:::code
        click GEM "https://github.com/googlecloudplatform/applied-ai-engineering-samples/tree/main/genai-on-vertex-ai/gemini/"
        click PR "https://github.com/googlecloudplatform/applied-ai-engineering-samples/tree/main/genai-on-vertex-ai/gemini/prompting_recipes/"
        click NH "https://github.com/googlecloudplatform/applied-ai-engineering-samples/tree/main/genai-on-vertex-ai/gemini/needle_in_a_haystack/"
        click RAG "https://github.com/googlecloudplatform/applied-ai-engineering-samples/tree/main/genai-on-vertex-ai/retrieval_augmented_generation/"
        click SAS "https://github.com/googlecloudplatform/applied-ai-engineering-samples/tree/main/genai-on-vertex-ai/vertex_ai_search/"
        click VES "https://github.com/googlecloudplatform/applied-ai-engineering-samples/tree/main/genai-on-vertex-ai/vertex_evaluation_services/"
        click AGT "https://github.com/googlecloudplatform/applied-ai-engineering-samples/tree/main/genai-on-vertex-ai/agents/"
    end

    GenAI --> GEM
    GenAI --> PR
    GenAI --> NH
    GenAI --> RAG
    GenAI --> SAS
    GenAI --> VES
    GenAI --> AGT

    %% Vertex AI Services
    GEM --> VM["Vertex AI Model Serving"]:::service
    VES --> VE["Vertex AI Evaluation"]:::service
    RAG --> VP["Vertex AI Pipelines"]:::service
    SAS --> VS["Vertex AI Search"]:::service
    AGT --> VA["Vertex AI Agents"]:::service

    %% Data flows
    GEM --> GCS
    VES --> BQ
    RAG --> GCS
    SAS --> GCS
    AGT --> GCS

    %% GKE and TPU jobs
    EX --> GKE
    IM --> GKE

    %% Research Operationalization
    Repo --> Research["Research Operationalization"]:::code
    click Research "https://github.com/googlecloudplatform/applied-ai-engineering-samples/blob/main/research-operationalization/README.md"

    subgraph "Research: timesfm"
        direction TB
        TS["operationalizing_timesfm_on_vertexai.ipynb"]:::code
        click TS "https://github.com/googlecloudplatform/applied-ai-engineering-samples/blob/main/research-operationalization/timesfm/operationalizing_timesfm_on_vertexai.ipynb"
    end

    Research --> TS
    TS --> VM
    TS --> GCS

    %% Styles
    classDef infra fill:#f9f,stroke:#333,stroke-width:1px;
    classDef compute fill:#bbf,stroke:#333,stroke-width:1px;
    classDef datastore fill:#bfb,stroke:#333,stroke-width:1px;
    classDef service fill:#fbf,stroke:#333,stroke-width:1px;
    classDef code fill:#fff,stroke:#333,stroke-width:1px;
    classDef doc fill:#ffb,stroke:#333,stroke-width:1px;
    classDef ci fill:#fbb,stroke:#333,stroke-width:1px;
    classDef repo fill:#ddd,stroke:#333,stroke-width:1px;
```
