# bhancockio/adk-fullstack-deploy-tutorial architecture

> Architecture diagram of the GitHub repository bhancockio/adk-fullstack-deploy-tutorial, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bhancockio/adk-fullstack-deploy-tutorial
- Repository: https://github.com/bhancockio/adk-fullstack-deploy-tutorial

## Overview

This is a fullstack goal-planning agent template: users create or select a session, submit a goal in chat, and receive streamed agent output and activity updates. The frontend routes streaming requests to either the local ADK backend or Vertex AI Agent Engine; session management and health checks are supporting branches. README documentation establishes capabilities whose implementation was not sampled, so those components are included only where the tree and docs support them.

Main entry points: [`nextjs/src/lib/streaming/connection-manager.ts`](https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/nextjs/src/lib/streaming/connection-manager.ts) (SSE connection), [`nextjs/src/app/api/run_sse/route.ts`](https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/nextjs/src/app/api/run_sse/route.ts) (Stream API route), [`nextjs/src/lib/handlers/run-sse-local-backend-handler.ts`](https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/nextjs/src/lib/handlers/run-sse-local-backend-handler.ts) (Local stream handler), [`nextjs/src/lib/handlers/run-sse-agent-engine-handler.ts`](https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/nextjs/src/lib/handlers/run-sse-agent-engine-handler.ts) (Agent Engine handler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Chat frontend"]
  node_chat["Chat UI<br/>[ChatContainer.tsx]"]
  node_manager["Streaming manager"]
  node_messagehook["Messages and events<br/>[useMessages.ts]"]
  node_timeline["Activity timeline"]
end

subgraph group_streaming["Streaming API"]
  node_connection["SSE connection"]
  node_processor["SSE event processor"]
  node_route["Stream API route<br/>[route.ts]"]
  node_config["Backend routing config<br/>[config.ts]"]
  node_localhandler["Local stream handler"]
  node_enginehandler["Agent Engine handler"]
  node_health["Health API route<br/>[route.ts]"]
end

subgraph group_agent["Agent runtime"]
  node_backend["ADK goal agent<br/>[agent.py]"]
  node_agentconfig["Cloud configuration<br/>[config.py]"]
  node_deploy["Agent Engine app"]
  node_localapi["Local ADK API"]
end

subgraph group_sessions["Session management"]
  node_sessionhook["Session state<br/>[useSession.ts]"]
  node_sessionselect["Session selection"]
  node_sessionactions["Session actions<br/>[session-actions.ts]"]
  node_sessionservice["Session service<br/>[session-service.ts]"]
  node_storage[("Browser message storage<br/>[useMessages.ts]")]
end

node_user(("User"))
node_engine["Vertex AI Agent Engine"]
node_model["Gemini model"]

node_user -->|"submits goal"| node_chat
node_chat -->|"starts stream"| node_manager
node_manager -->|"sends request"| node_connection
node_connection -->|"POSTs stream"| node_route
node_route -->|"selects backend"| node_config
node_route -->|"dispatches local"| node_localhandler
node_route -->|"dispatches engine"| node_enginehandler
node_localhandler -->|"resolves endpoint"| node_config
node_localhandler -->|"forwards stream"| node_localapi
node_enginehandler -->|"resolves endpoint"| node_config
node_enginehandler -.->|"streams request"| node_engine
node_localapi -->|"runs agent"| node_backend
node_engine -.->|"runs deployed agent"| node_backend
node_backend -->|"plans with"| node_model
node_enginehandler -->|"returns SSE"| node_connection
node_localhandler -->|"returns SSE"| node_connection
node_connection -->|"processes events"| node_processor
node_processor -->|"updates messages"| node_messagehook
node_processor -->|"updates activity"| node_timeline
node_chat -->|"manages session"| node_sessionhook
node_sessionselect -->|"switches session"| node_sessionhook
node_sessionhook -->|"creates session"| node_sessionactions
node_sessionactions -->|"invokes service"| node_sessionservice
node_sessionservice -->|"creates session"| node_localapi
node_sessionservice -.->|"creates session"| node_engine
node_messagehook -->|"reads and writes"| node_storage
node_health -->|"proxies health"| node_localapi
node_agentconfig -->|"configures deployment"| node_deploy
node_deploy -->|"deploys agent"| node_engine

click node_chat "https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/nextjs/src/components/chat/ChatContainer.tsx"
click node_manager "https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/nextjs/src/components/chat/StreamingManager.tsx"
click node_sessionhook "https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/nextjs/src/hooks/useSession.ts"
click node_messagehook "https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/nextjs/src/hooks/useMessages.ts"
click node_timeline "https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/nextjs/src/components/ActivityTimeline.tsx"
click node_connection "https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/nextjs/src/lib/streaming/connection-manager.ts"
click node_processor "https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/nextjs/src/lib/streaming/stream-processor.ts"
click node_route "https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/nextjs/src/app/api/run_sse/route.ts"
click node_config "https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/nextjs/src/lib/config.ts"
click node_localhandler "https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/nextjs/src/lib/handlers/run-sse-local-backend-handler.ts"
click node_enginehandler "https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/nextjs/src/lib/handlers/run-sse-agent-engine-handler.ts"
click node_backend "https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/app/agent.py"
click node_agentconfig "https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/app/config.py"
click node_deploy "https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/app/agent_engine_app.py"
click node_sessionselect "https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/nextjs/src/components/chat/SessionSelector.tsx"
click node_sessionactions "https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/nextjs/src/lib/actions/session-actions.ts"
click node_sessionservice "https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/nextjs/src/lib/services/session-service.ts"
click node_storage "https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/nextjs/src/hooks/useMessages.ts"
click node_health "https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/nextjs/src/app/api/health/route.ts"

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_chat,node_manager,node_messagehook,node_timeline,node_user toneBlue
class node_connection,node_processor,node_route,node_config,node_localhandler,node_enginehandler,node_health toneAmber
class node_backend,node_agentconfig,node_deploy,node_localapi toneMint
class node_sessionhook,node_sessionselect,node_sessionactions,node_sessionservice,node_storage toneRose
class node_engine,node_model toneIndigo
```

## Components

### Chat frontend

- [Chat UI](https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/nextjs/src/components/chat/ChatContainer.tsx): `nextjs/src/components/chat/ChatContainer.tsx`
- [Streaming manager](https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/nextjs/src/components/chat/StreamingManager.tsx): `nextjs/src/components/chat/StreamingManager.tsx`
- [Messages and events](https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/nextjs/src/hooks/useMessages.ts): `nextjs/src/hooks/useMessages.ts`
- [Activity timeline](https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/nextjs/src/components/ActivityTimeline.tsx): `nextjs/src/components/ActivityTimeline.tsx`

### Streaming API

- [SSE connection](https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/nextjs/src/lib/streaming/connection-manager.ts): `nextjs/src/lib/streaming/connection-manager.ts`
- [SSE event processor](https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/nextjs/src/lib/streaming/stream-processor.ts): `nextjs/src/lib/streaming/stream-processor.ts`
- [Stream API route](https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/nextjs/src/app/api/run_sse/route.ts): `nextjs/src/app/api/run_sse/route.ts`
- [Backend routing config](https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/nextjs/src/lib/config.ts): `nextjs/src/lib/config.ts`
- [Local stream handler](https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/nextjs/src/lib/handlers/run-sse-local-backend-handler.ts): `nextjs/src/lib/handlers/run-sse-local-backend-handler.ts`
- [Agent Engine handler](https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/nextjs/src/lib/handlers/run-sse-agent-engine-handler.ts): `nextjs/src/lib/handlers/run-sse-agent-engine-handler.ts`
- [Health API route](https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/nextjs/src/app/api/health/route.ts): `nextjs/src/app/api/health/route.ts`

### Agent runtime

- [ADK goal agent](https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/app/agent.py): `app/agent.py`
- [Cloud configuration](https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/app/config.py): `app/config.py`
- [Agent Engine app](https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/app/agent_engine_app.py): `app/agent_engine_app.py`
- **Local ADK API**

### Session management

- [Session state](https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/nextjs/src/hooks/useSession.ts): `nextjs/src/hooks/useSession.ts`
- [Session selection](https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/nextjs/src/components/chat/SessionSelector.tsx): `nextjs/src/components/chat/SessionSelector.tsx`
- [Session actions](https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/nextjs/src/lib/actions/session-actions.ts): `nextjs/src/lib/actions/session-actions.ts`
- [Session service](https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/nextjs/src/lib/services/session-service.ts): `nextjs/src/lib/services/session-service.ts`
- [Browser message storage](https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/nextjs/src/hooks/useMessages.ts): `nextjs/src/hooks/useMessages.ts`

### Other components

- **User**
- **Vertex AI Agent Engine**
- **Gemini model**

## Connections

- User → Chat UI: submits goal
- Chat UI → Streaming manager: starts stream
- Streaming manager → SSE connection: sends request
- SSE connection → Stream API route: POSTs stream
- Stream API route → Backend routing config: selects backend
- Stream API route → Local stream handler: dispatches local
- Stream API route → Agent Engine handler: dispatches engine
- Local stream handler → Backend routing config: resolves endpoint
- Local stream handler → Local ADK API: forwards stream
- Agent Engine handler → Backend routing config: resolves endpoint
- Agent Engine handler → Vertex AI Agent Engine: streams request
- Local ADK API → ADK goal agent: runs agent
- Vertex AI Agent Engine → ADK goal agent: runs deployed agent
- ADK goal agent → Gemini model: plans with
- Agent Engine handler → SSE connection: returns SSE
- Local stream handler → SSE connection: returns SSE
- SSE connection → SSE event processor: processes events
- SSE event processor → Messages and events: updates messages
- SSE event processor → Activity timeline: updates activity
- Chat UI → Session state: manages session
- Session selection → Session state: switches session
- Session state → Session actions: creates session
- Session actions → Session service: invokes service
- Session service → Local ADK API: creates session
- Session service → Vertex AI Agent Engine: creates session
- Messages and events → Browser message storage: reads and writes
- Health API route → Local ADK API: proxies health
- Cloud configuration → Agent Engine app: configures deployment
- Agent Engine app → Vertex AI Agent Engine: deploys agent