# google-gemini/gemini-fullstack-langgraph-quickstart architecture

> Architecture diagram of the GitHub repository google-gemini/gemini-fullstack-langgraph-quickstart, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/google-gemini/gemini-fullstack-langgraph-quickstart
- Repository: https://github.com/google-gemini/gemini-fullstack-langgraph-quickstart

## Overview

1. **Overall shape**
   This is a two-tier fullstack repo: a **React/Vite frontend** in `frontend/` and a **Python LangGraph backend agent** in `backend/`. The main architectural boundary is between the browser UI and the research agent API.

2. **Frontend subsystem**
   The frontend is a single-page app built with **React + TypeScript + Vite**. Its main entry is `frontend/src/main.tsx`, which mounts `App.tsx`. The UI is composed from a small set of feature components: chat/message display, an input form, a welcome screen, and an activity timeline.

3. **Frontend interaction model**
   The frontend appears to be a conversational research interface rather than a generic CRUD app. `ChatMessagesView.tsx` and `InputForm.tsx` suggest the user submits a research question and receives streamed or incremental agent output. `ActivityTimeline.tsx` likely visualizes the agent’s internal steps, which is important for understanding the system’s “reasoning + research” flow.

4. **Backend agent subsystem**
   The backend is a **LangGraph-powered research agent** under `backend/src/agent/`. The core orchestration is in `graph.py`, with supporting modules for prompts, tools/schemas, state, configuration, utilities, and app wiring. This is the heart of the application and defines how the research workflow progresses.

5. **Agent workflow**
   The agent follows an iterative loop: generate search queries, perform web research, reflect on gaps, refine queries, and then synthesize a final answer with citations. This means the backend is not a simple request/response model call; it is a **multi-step graph workflow** with state carried across nodes and iterations.

6. **Model and search integration**
   The repository is built around **Google Gemini** for query generation, reflection, and final answer synthesis, plus **Google Search** for retrieval. The external service boundary is therefore: user input enters the backend, Gemini drives reasoning, search supplies evidence, and the agent returns a supported response.

7. **Backend application boundary**
   `backend/src/agent/app.py` likely exposes the agent as an API-compatible application for LangGraph deployment/dev mode, while `langgraph.json` indicates LangGraph-specific runtime configuration. The README notes `langgraph dev` as the local backend runner, so the backend is treated as a deployable agent service rather than a custom hand-written web server.

8. **State and schema design**
   `state.py` and `tools_and_schemas.py` indicate that the agent uses explicit structured state and tool contracts. That’s important architecturally: each loop of the graph can persist research context, source data, and intermediate decisions, enabling the reflection/refinement cycle and citation assembly.

9. **CLI and non-UI entrypoint**
   `backend/examples/cli_research.py` provides a command-line execution path for the same agent logic. This shows the research graph is separated from the UI and can be invoked independently, which is useful when diagramming shared backend logic versus presentation layers.

10. **Deployment/runtime topology**
   In development, `make dev` runs both frontend and backend. In production, the backend serves the optimized frontend build from Docker, and the README notes LangGraph deployment dependencies on **Redis** and **Postgres** for streaming, run coordination, thread state, and persistence. That means the production architecture is: browser → backend agent API → Redis/Postgres + Gemini/Search services, with the backend also acting as the static frontend host.

11. **UI library and styling**
   The frontend uses a lightweight component system built from local UI primitives under `frontend/src/components/ui/`, with Tailwind/shadcn-style patterns. This affects architecture mainly as a presentation concern: the app is modular at the component level, but the primary system boundary remains the frontend-backend split.

12. **What to draw in an architecture diagram**
   Show: user/browser, React SPA, backend LangGraph agent, Gemini, Google Search, Redis, Postgres, and optional CLI entrypoint. Emphasize the agent’s internal loop as a stateful workflow with iterative retrieval and reflection, not a one-shot LLM call.

Main entry points: [`backend/src/agent/graph.py`](https://github.com/google-gemini/gemini-fullstack-langgraph-quickstart/blob/main/backend/src/agent/graph.py) (Graph), [`backend/src/agent/app.py`](https://github.com/google-gemini/gemini-fullstack-langgraph-quickstart/blob/main/backend/src/agent/app.py) (Agent API), [`frontend/src/App.tsx`](https://github.com/google-gemini/gemini-fullstack-langgraph-quickstart/blob/main/frontend/src/App.tsx) (App), [`frontend/src/main.tsx`](https://github.com/google-gemini/gemini-fullstack-langgraph-quickstart/blob/main/frontend/src/main.tsx) (Entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_frontend["Frontend"]
  node_node_main["Entry<br/>[main.tsx]"]
  node_node_app["App<br/>spa shell<br/>[App.tsx]"]
  node_node_chat["Messages<br/>chat view"]
  node_node_input["Input<br/>question form<br/>[InputForm.tsx]"]
  node_node_timeline["Timeline<br/>activity view"]
  node_node_welcome["Welcome<br/>landing view<br/>[WelcomeScreen.tsx]"]
end

subgraph group_group_backend["Backend"]
  node_node_backend_app["Agent API<br/>langgraph app<br/>[app.py]"]
  node_node_graph{{"Graph<br/>workflow engine<br/>[graph.py]"}}
  node_node_state["State<br/>[state.py]"]
  node_node_tools["Tools"]
  node_node_prompts["Prompts<br/>prompt templates<br/>[prompts.py]"]
  node_node_config["Config<br/>[configuration.py]"]
  node_node_utils["Utils<br/>helpers<br/>[utils.py]"]
  node_node_cli["CLI<br/>[cli_research.py]"]
end

subgraph group_group_external["External services"]
  node_node_gemini(("Gemini<br/>llm provider"))
  node_node_search(("Search<br/>web retrieval"))
  node_node_store[("Redis/Postgres<br/>persistence")]
end

node_node_browser(("Browser<br/>user/client"))

node_node_browser -->|"opens"| node_node_main
node_node_main -->|"mounts"| node_node_app
node_node_app -->|"renders"| node_node_chat
node_node_app -->|"renders"| node_node_input
node_node_app -->|"renders"| node_node_timeline
node_node_app -->|"shows"| node_node_welcome
node_node_input -->|"submits query"| node_node_backend_app
node_node_chat -->|"streams output"| node_node_backend_app
node_node_timeline -->|"tracks steps"| node_node_backend_app
node_node_backend_app -->|"invokes"| node_node_graph
node_node_graph -->|"reads/writes"| node_node_state
node_node_graph -->|"uses"| node_node_prompts
node_node_graph -->|"uses"| node_node_tools
node_node_graph -->|"calls"| node_node_utils
node_node_graph -->|"reasons with"| node_node_gemini
node_node_graph -->|"retrieves"| node_node_search
node_node_backend_app -->|"persists"| node_node_store
node_node_backend_app -->|"shares logic"| node_node_cli
node_node_cli -->|"runs"| node_node_graph
node_node_backend_app -->|"serves"| node_node_graph

click node_node_main "https://github.com/google-gemini/gemini-fullstack-langgraph-quickstart/blob/main/frontend/src/main.tsx"
click node_node_app "https://github.com/google-gemini/gemini-fullstack-langgraph-quickstart/blob/main/frontend/src/App.tsx"
click node_node_chat "https://github.com/google-gemini/gemini-fullstack-langgraph-quickstart/blob/main/frontend/src/components/ChatMessagesView.tsx"
click node_node_input "https://github.com/google-gemini/gemini-fullstack-langgraph-quickstart/blob/main/frontend/src/components/InputForm.tsx"
click node_node_timeline "https://github.com/google-gemini/gemini-fullstack-langgraph-quickstart/blob/main/frontend/src/components/ActivityTimeline.tsx"
click node_node_welcome "https://github.com/google-gemini/gemini-fullstack-langgraph-quickstart/blob/main/frontend/src/components/WelcomeScreen.tsx"
click node_node_backend_app "https://github.com/google-gemini/gemini-fullstack-langgraph-quickstart/blob/main/backend/src/agent/app.py"
click node_node_graph "https://github.com/google-gemini/gemini-fullstack-langgraph-quickstart/blob/main/backend/src/agent/graph.py"
click node_node_state "https://github.com/google-gemini/gemini-fullstack-langgraph-quickstart/blob/main/backend/src/agent/state.py"
click node_node_tools "https://github.com/google-gemini/gemini-fullstack-langgraph-quickstart/blob/main/backend/src/agent/tools_and_schemas.py"
click node_node_prompts "https://github.com/google-gemini/gemini-fullstack-langgraph-quickstart/blob/main/backend/src/agent/prompts.py"
click node_node_config "https://github.com/google-gemini/gemini-fullstack-langgraph-quickstart/blob/main/backend/src/agent/configuration.py"
click node_node_utils "https://github.com/google-gemini/gemini-fullstack-langgraph-quickstart/blob/main/backend/src/agent/utils.py"
click node_node_cli "https://github.com/google-gemini/gemini-fullstack-langgraph-quickstart/blob/main/backend/examples/cli_research.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_node_main,node_node_app,node_node_chat,node_node_input,node_node_timeline,node_node_welcome toneBlue
class node_node_backend_app,node_node_graph,node_node_state,node_node_tools,node_node_prompts,node_node_config,node_node_utils,node_node_cli toneAmber
class node_node_gemini,node_node_search,node_node_store toneMint
class node_node_browser toneNeutral
```

## Components

### Frontend

React/Vite SPA for conversational research

- [Entry](https://github.com/google-gemini/gemini-fullstack-langgraph-quickstart/blob/main/frontend/src/main.tsx): vite entry · Bootstraps the React app · `frontend/src/main.tsx`
- [App](https://github.com/google-gemini/gemini-fullstack-langgraph-quickstart/blob/main/frontend/src/App.tsx): spa shell · Top-level frontend composition and state · `frontend/src/App.tsx`
- [Messages](https://github.com/google-gemini/gemini-fullstack-langgraph-quickstart/blob/main/frontend/src/components/ChatMessagesView.tsx): chat view · Renders the conversational research transcript · `frontend/src/components/ChatMessagesView.tsx`
- [Input](https://github.com/google-gemini/gemini-fullstack-langgraph-quickstart/blob/main/frontend/src/components/InputForm.tsx): question form · Collects research prompts from the user · `frontend/src/components/InputForm.tsx`
- [Timeline](https://github.com/google-gemini/gemini-fullstack-langgraph-quickstart/blob/main/frontend/src/components/ActivityTimeline.tsx): activity view · Shows the agent’s step-by-step progress · `frontend/src/components/ActivityTimeline.tsx`
- [Welcome](https://github.com/google-gemini/gemini-fullstack-langgraph-quickstart/blob/main/frontend/src/components/WelcomeScreen.tsx): landing view · Initial empty-state guidance · `frontend/src/components/WelcomeScreen.tsx`

### Backend

LangGraph research agent service

- [Agent API](https://github.com/google-gemini/gemini-fullstack-langgraph-quickstart/blob/main/backend/src/agent/app.py): langgraph app · Backend application boundary for the research agent · `backend/src/agent/app.py`
- [Graph](https://github.com/google-gemini/gemini-fullstack-langgraph-quickstart/blob/main/backend/src/agent/graph.py): workflow engine · Core LangGraph orchestration and iterative loop · `backend/src/agent/graph.py`
- [State](https://github.com/google-gemini/gemini-fullstack-langgraph-quickstart/blob/main/backend/src/agent/state.py): agent state · Shared structured state across graph steps · `backend/src/agent/state.py`
- [Tools](https://github.com/google-gemini/gemini-fullstack-langgraph-quickstart/blob/main/backend/src/agent/tools_and_schemas.py): schemas/tools · Tool contracts and structured schemas · `backend/src/agent/tools_and_schemas.py`
- [Prompts](https://github.com/google-gemini/gemini-fullstack-langgraph-quickstart/blob/main/backend/src/agent/prompts.py): prompt templates · Instructions for query generation and synthesis · `backend/src/agent/prompts.py`
- [Config](https://github.com/google-gemini/gemini-fullstack-langgraph-quickstart/blob/main/backend/src/agent/configuration.py): runtime config · Environment and deployment settings · `backend/src/agent/configuration.py`
- [Utils](https://github.com/google-gemini/gemini-fullstack-langgraph-quickstart/blob/main/backend/src/agent/utils.py): helpers · Shared agent helper functions · `backend/src/agent/utils.py`
- [CLI](https://github.com/google-gemini/gemini-fullstack-langgraph-quickstart/blob/main/backend/examples/cli_research.py): research cli · Command-line entrypoint for the same agent logic · `backend/examples/cli_research.py`

### External services

Model, search, and persistence dependencies

- **Gemini**: llm provider · Model backend for reasoning and synthesis
- **Search**: web retrieval · Google Search evidence source
- **Redis/Postgres**: persistence · Streaming, thread state, and run coordination storage

### Other components

- **Browser**: user/client · Person using the research UI

## Connections

- Browser → Entry: opens · User loads the frontend app
- Entry → App: mounts · React entry mounts the SPA shell
- App → Messages: renders · Chat transcript area
- App → Input: renders · Question submission form
- App → Timeline: renders · Agent progress visualization
- App → Welcome: shows · Initial empty-state screen
- Input → Agent API: submits query · User question is sent to the agent service
- Messages → Agent API: streams output · Incremental agent messages flow back to the UI
- Timeline → Agent API: tracks steps · Displays agent execution progress
- Agent API → Graph: invokes · Application boundary dispatches into the workflow graph
- Graph → State: reads/writes · Carries research context across iterations
- Graph → Prompts: uses · Prompt templates guide generation and synthesis
- Graph → Tools: uses · Structured tool and schema definitions
- Graph → Utils: calls · Shared helper functions support workflow steps
- Graph → Gemini: reasons with · LLM drives query generation, reflection, and final answer
- Graph → Search: retrieves · Search is used to gather supporting evidence
- Agent API → Redis/Postgres: persists · Runtime uses external storage for threads and streaming
- Agent API → CLI: shares logic · CLI path reuses the same research agent workflow
- CLI → Graph: runs · Command-line execution enters the workflow graph
- Agent API → Graph: serves · Backend API exposes the graph as the main service
