# googlecloudplatform/terraform-genai-rag architecture

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

- Interactive diagram: https://gitdiagram.com/googlecloudplatform/terraform-genai-rag
- Repository: https://github.com/googlecloudplatform/terraform-genai-rag

## Overview

This is an airline customer-service RAG application: users chat about airports, flights, amenities, policies, and ticket booking; the assistant invokes tools that query a separate retrieval API and may require confirmation before ticket insertion. The frontend supports three orchestration strategies, while the retrieval service exposes API routes over configurable datastore providers and embeddings. Evaluation includes golden tool-call scenarios and retrieval/response evaluation. Several runtime details are unsampled, so uncertain provider dispatch and cross-service wiring are left out rather than inferred.

Main entry points: [`src/retrieval_service/datastore/datastore.py`](https://github.com/googlecloudplatform/terraform-genai-rag/blob/main/src/retrieval_service/datastore/datastore.py) (Datastore interface), [`src/frontend_service/orchestrator/orchestrator.py`](https://github.com/googlecloudplatform/terraform-genai-rag/blob/main/src/frontend_service/orchestrator/orchestrator.py) (Orchestrator interface), [`src/retrieval_service/app/routes.py`](https://github.com/googlecloudplatform/terraform-genai-rag/blob/main/src/retrieval_service/app/routes.py) (Search and ticket routes), [`src/frontend_service/orchestrator/langgraph/react_graph.py`](https://github.com/googlecloudplatform/terraform-genai-rag/blob/main/src/frontend_service/orchestrator/langgraph/react_graph.py) (ReAct graph)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Chat frontend"]
  node_webapp["Chat routes<br/>[app.py]"]
  node_evaluation["Assistant evaluation<br/>[evaluation.py]"]
  node_goldens["Golden scenarios<br/>[eval_golden.py]"]
end

subgraph group_orchestration["Assistant orchestration"]
  node_baseorc["Orchestrator interface<br/>[orchestrator.py]"]
  node_langchain["LangChain agent"]
  node_langchain_tools["LangChain tools<br/>[tools.py]"]
  node_langgraph["LangGraph agent"]
  node_react["ReAct graph<br/>[react_graph.py]"]
  node_lgtools["Graph tools<br/>[tools.py]"]
  node_toolnode["Tool execution node<br/>[tool_node.py]"]
  node_vertex["Vertex function calling"]
  node_vertexfuncs["Function definitions<br/>[functions.py]"]
end

subgraph group_retrieval["Retrieval service"]
  node_retrieval_api["Retrieval API<br/>[app.py]"]
  node_routes["Search and ticket routes<br/>[routes.py]"]
end

subgraph group_persistence["Data and storage"]
  node_datastore["Datastore interface<br/>[datastore.py]"]
  node_models["Airline data models<br/>[models.py]"]
  node_postgres[("PostgreSQL provider<br/>[postgres.py]")]
  node_cloudsql[("Cloud SQL provider")]
  node_firestore[("Firestore provider<br/>[firestore.py]")]
end

node_user(("Customer"))
node_vertex_embeddings["Vertex embeddings"]

node_user -->|"submits chat"| node_webapp
node_webapp -->|"invokes session"| node_baseorc
node_baseorc -.->|"selects strategy"| node_langchain
node_baseorc -.->|"selects strategy"| node_langgraph
node_baseorc -.->|"selects strategy"| node_vertex
node_langchain -->|"uses tools"| node_langchain_tools
node_langgraph -->|"invokes graph"| node_react
node_react -->|"uses tools"| node_lgtools
node_react -->|"dispatches tools"| node_toolnode
node_vertex -->|"uses functions"| node_vertexfuncs
node_evaluation -->|"evaluates sessions"| node_baseorc
node_evaluation -->|"loads scenarios"| node_goldens
node_lgtools -->|"requests search"| node_routes
node_retrieval_api -->|"registers routes"| node_routes
node_retrieval_api -->|"creates datastore"| node_datastore
node_routes -->|"queries data"| node_datastore
node_routes -.->|"embeds query"| node_vertex_embeddings
node_datastore -->|"uses models"| node_models
node_postgres -->|"implements interface"| node_datastore
node_cloudsql -->|"implements interface"| node_datastore
node_firestore -->|"implements interface"| node_datastore

click node_webapp "https://github.com/googlecloudplatform/terraform-genai-rag/blob/main/src/frontend_service/app.py"
click node_evaluation "https://github.com/googlecloudplatform/terraform-genai-rag/blob/main/src/frontend_service/evaluation/evaluation.py"
click node_goldens "https://github.com/googlecloudplatform/terraform-genai-rag/blob/main/src/frontend_service/evaluation/eval_golden.py"
click node_baseorc "https://github.com/googlecloudplatform/terraform-genai-rag/blob/main/src/frontend_service/orchestrator/orchestrator.py"
click node_langchain "https://github.com/googlecloudplatform/terraform-genai-rag/blob/main/src/frontend_service/orchestrator/langchain_tools/langchain_tools_orchestrator.py"
click node_langchain_tools "https://github.com/googlecloudplatform/terraform-genai-rag/blob/main/src/frontend_service/orchestrator/langchain_tools/tools.py"
click node_langgraph "https://github.com/googlecloudplatform/terraform-genai-rag/blob/main/src/frontend_service/orchestrator/langgraph/langgraph_orchestrator.py"
click node_react "https://github.com/googlecloudplatform/terraform-genai-rag/blob/main/src/frontend_service/orchestrator/langgraph/react_graph.py"
click node_lgtools "https://github.com/googlecloudplatform/terraform-genai-rag/blob/main/src/frontend_service/orchestrator/langgraph/tools.py"
click node_toolnode "https://github.com/googlecloudplatform/terraform-genai-rag/blob/main/src/frontend_service/orchestrator/langgraph/tool_node.py"
click node_vertex "https://github.com/googlecloudplatform/terraform-genai-rag/blob/main/src/frontend_service/orchestrator/vertexai_function_calling/function_calling_orchestrator.py"
click node_vertexfuncs "https://github.com/googlecloudplatform/terraform-genai-rag/blob/main/src/frontend_service/orchestrator/vertexai_function_calling/functions.py"
click node_retrieval_api "https://github.com/googlecloudplatform/terraform-genai-rag/blob/main/src/retrieval_service/app/app.py"
click node_routes "https://github.com/googlecloudplatform/terraform-genai-rag/blob/main/src/retrieval_service/app/routes.py"
click node_datastore "https://github.com/googlecloudplatform/terraform-genai-rag/blob/main/src/retrieval_service/datastore/datastore.py"
click node_models "https://github.com/googlecloudplatform/terraform-genai-rag/blob/main/src/retrieval_service/models/models.py"
click node_postgres "https://github.com/googlecloudplatform/terraform-genai-rag/blob/main/src/retrieval_service/datastore/providers/postgres.py"
click node_cloudsql "https://github.com/googlecloudplatform/terraform-genai-rag/blob/main/src/retrieval_service/datastore/providers/cloudsql_postgres.py"
click node_firestore "https://github.com/googlecloudplatform/terraform-genai-rag/blob/main/src/retrieval_service/datastore/providers/firestore.py"

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_webapp,node_evaluation,node_goldens toneBlue
class node_baseorc,node_langchain,node_langchain_tools,node_langgraph,node_react,node_lgtools,node_toolnode,node_vertex,node_vertexfuncs toneAmber
class node_retrieval_api,node_routes toneMint
class node_datastore,node_models,node_postgres,node_cloudsql,node_firestore toneRose
class node_user,node_vertex_embeddings toneIndigo
```

## Components

### Chat frontend

- [Chat routes](https://github.com/googlecloudplatform/terraform-genai-rag/blob/main/src/frontend_service/app.py): `src/frontend_service/app.py`
- [Assistant evaluation](https://github.com/googlecloudplatform/terraform-genai-rag/blob/main/src/frontend_service/evaluation/evaluation.py): `src/frontend_service/evaluation/evaluation.py`
- [Golden scenarios](https://github.com/googlecloudplatform/terraform-genai-rag/blob/main/src/frontend_service/evaluation/eval_golden.py): `src/frontend_service/evaluation/eval_golden.py`

### Assistant orchestration

- [Orchestrator interface](https://github.com/googlecloudplatform/terraform-genai-rag/blob/main/src/frontend_service/orchestrator/orchestrator.py): `src/frontend_service/orchestrator/orchestrator.py`
- [LangChain agent](https://github.com/googlecloudplatform/terraform-genai-rag/blob/main/src/frontend_service/orchestrator/langchain_tools/langchain_tools_orchestrator.py): `src/frontend_service/orchestrator/langchain_tools/langchain_tools_orchestrator.py`
- [LangChain tools](https://github.com/googlecloudplatform/terraform-genai-rag/blob/main/src/frontend_service/orchestrator/langchain_tools/tools.py): `src/frontend_service/orchestrator/langchain_tools/tools.py`
- [LangGraph agent](https://github.com/googlecloudplatform/terraform-genai-rag/blob/main/src/frontend_service/orchestrator/langgraph/langgraph_orchestrator.py): `src/frontend_service/orchestrator/langgraph/langgraph_orchestrator.py`
- [ReAct graph](https://github.com/googlecloudplatform/terraform-genai-rag/blob/main/src/frontend_service/orchestrator/langgraph/react_graph.py): `src/frontend_service/orchestrator/langgraph/react_graph.py`
- [Graph tools](https://github.com/googlecloudplatform/terraform-genai-rag/blob/main/src/frontend_service/orchestrator/langgraph/tools.py): `src/frontend_service/orchestrator/langgraph/tools.py`
- [Tool execution node](https://github.com/googlecloudplatform/terraform-genai-rag/blob/main/src/frontend_service/orchestrator/langgraph/tool_node.py): `src/frontend_service/orchestrator/langgraph/tool_node.py`
- [Vertex function calling](https://github.com/googlecloudplatform/terraform-genai-rag/blob/main/src/frontend_service/orchestrator/vertexai_function_calling/function_calling_orchestrator.py): `src/frontend_service/orchestrator/vertexai_function_calling/function_calling_orchestrator.py`
- [Function definitions](https://github.com/googlecloudplatform/terraform-genai-rag/blob/main/src/frontend_service/orchestrator/vertexai_function_calling/functions.py): `src/frontend_service/orchestrator/vertexai_function_calling/functions.py`

### Retrieval service

- [Retrieval API](https://github.com/googlecloudplatform/terraform-genai-rag/blob/main/src/retrieval_service/app/app.py): `src/retrieval_service/app/app.py`
- [Search and ticket routes](https://github.com/googlecloudplatform/terraform-genai-rag/blob/main/src/retrieval_service/app/routes.py): `src/retrieval_service/app/routes.py`

### Data and storage

- [Datastore interface](https://github.com/googlecloudplatform/terraform-genai-rag/blob/main/src/retrieval_service/datastore/datastore.py): `src/retrieval_service/datastore/datastore.py`
- [Airline data models](https://github.com/googlecloudplatform/terraform-genai-rag/blob/main/src/retrieval_service/models/models.py): `src/retrieval_service/models/models.py`
- [PostgreSQL provider](https://github.com/googlecloudplatform/terraform-genai-rag/blob/main/src/retrieval_service/datastore/providers/postgres.py): `src/retrieval_service/datastore/providers/postgres.py`
- [Cloud SQL provider](https://github.com/googlecloudplatform/terraform-genai-rag/blob/main/src/retrieval_service/datastore/providers/cloudsql_postgres.py): `src/retrieval_service/datastore/providers/cloudsql_postgres.py`
- [Firestore provider](https://github.com/googlecloudplatform/terraform-genai-rag/blob/main/src/retrieval_service/datastore/providers/firestore.py): `src/retrieval_service/datastore/providers/firestore.py`

### Other components

- **Customer**
- **Vertex embeddings**

## Connections

- Customer → Chat routes: submits chat (evidence: `src/frontend_service/app.py`)
- Chat routes → Orchestrator interface: invokes session (evidence: `src/frontend_service/app.py`)
- Orchestrator interface → LangChain agent: selects strategy (evidence: `src/frontend_service/orchestrator/langchain_tools/langchain_tools_orchestrator.py`)
- Orchestrator interface → LangGraph agent: selects strategy (evidence: `src/frontend_service/orchestrator/langgraph/langgraph_orchestrator.py`)
- Orchestrator interface → Vertex function calling: selects strategy (evidence: `src/frontend_service/orchestrator/vertexai_function_calling/function_calling_orchestrator.py`)
- LangChain agent → LangChain tools: uses tools (evidence: `src/frontend_service/orchestrator/langchain_tools/langchain_tools_orchestrator.py`)
- LangGraph agent → ReAct graph: invokes graph (evidence: `src/frontend_service/orchestrator/langgraph/langgraph_orchestrator.py`)
- ReAct graph → Graph tools: uses tools (evidence: `src/frontend_service/orchestrator/langgraph/react_graph.py`)
- ReAct graph → Tool execution node: dispatches tools (evidence: `src/frontend_service/orchestrator/langgraph/react_graph.py`)
- Vertex function calling → Function definitions: uses functions (evidence: `src/frontend_service/orchestrator/vertexai_function_calling/function_calling_orchestrator.py`)
- Assistant evaluation → Orchestrator interface: evaluates sessions (evidence: `src/frontend_service/evaluation/evaluation.py`)
- Assistant evaluation → Golden scenarios: loads scenarios (evidence: `src/frontend_service/evaluation/evaluation.py`)
- Graph tools → Search and ticket routes: requests search (evidence: `src/frontend_service/orchestrator/langgraph/tools.py`)
- Retrieval API → Search and ticket routes: registers routes (evidence: `src/retrieval_service/app/app.py`)
- Retrieval API → Datastore interface: creates datastore (evidence: `src/retrieval_service/app/app.py`)
- Search and ticket routes → Datastore interface: queries data (evidence: `src/retrieval_service/app/routes.py`)
- Search and ticket routes → Vertex embeddings: embeds query
- Datastore interface → Airline data models: uses models (evidence: `src/retrieval_service/datastore/datastore.py`)
- PostgreSQL provider → Datastore interface: implements interface (evidence: `src/retrieval_service/datastore/providers/postgres.py`)
- Cloud SQL provider → Datastore interface: implements interface (evidence: `src/retrieval_service/datastore/providers/cloudsql_postgres.py`)
- Firestore provider → Datastore interface: implements interface (evidence: `src/retrieval_service/datastore/providers/firestore.py`)
