How google-gemini/gemini-fullstack-langgraph-quickstart works
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: graph.py Graph · app.py Agent API · App.tsx App · main.tsx Entry
Components 18
Frontend
React/Vite SPA for conversational research
- Entry · Bootstraps the React app
frontend/src/main.tsx - App · Top-level frontend composition and state
frontend/src/App.tsx - Messages · Renders the conversational research transcript
frontend/src/components/ChatMessagesView.tsx - Input · Collects research prompts from the user
frontend/src/components/InputForm.tsx - Timeline · Shows the agent’s step-by-step progress
frontend/src/components/ActivityTimeline.tsx - Welcome · Initial empty-state guidance
frontend/src/components/WelcomeScreen.tsx
Backend
LangGraph research agent service
- Agent API · Backend application boundary for the research agent
backend/src/agent/app.py - Graph · Core LangGraph orchestration and iterative loop
backend/src/agent/graph.py - State · Shared structured state across graph steps
backend/src/agent/state.py - Tools · Tool contracts and structured schemas
backend/src/agent/tools_and_schemas.py - Prompts · Instructions for query generation and synthesis
backend/src/agent/prompts.py - Config · Environment and deployment settings
backend/src/agent/configuration.py - Utils · Shared agent helper functions
backend/src/agent/utils.py - CLI · Command-line entrypoint for the same agent logic
backend/examples/cli_research.py
External services
Model, search, and persistence dependencies
- Gemini · Model backend for reasoning and synthesis
- Search · Google Search evidence source
- Redis/Postgres · Streaming, thread state, and run coordination storage
Other components
- Browser · Person using the research UI
Connections 20
- 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