# liuyuwei/google-adk-server-example architecture

> Architecture diagram of the GitHub repository liuyuwei/google-adk-server-example, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/liuyuwei/google-adk-server-example
- Repository: https://github.com/liuyuwei/google-adk-server-example

## Overview

##### Project Type and Purpose
- Type: A single-service backend application (no separate frontend) built with Python/FastAPI and containerized with Docker.
- Purpose: Demonstrate how to expose Google ADK (GenAI or Vertex AI) functionality over an HTTP API.

##### File Structure
- Top-level:
– Dockerfile (builds container)
– .env.template / .env (environment variables for API keys & configuration)
– requirements.txt (Python dependencies)
– app/agent.py (FastAPI app + business logic)
- No separate “frontend” or “database” directories; this is a stateless microservice.
- README.md describes runtime steps, environment variables, and endpoints (/docs via SwaggerUI).

##### README for Insights
- Shows bootstrapping steps (copy .env, set GOOGLE_API_KEY or VertexAI vars).
- Indicates the main entrypoint is the FastAPI server (invoked via `adk api_server` in Docker).
- Exposes port 8000 for HTTP clients.

##### Main Components & Interactions
1. HTTP Client / Consumer (e.g., curl, a frontend app, or SwaggerUI)
2. Docker Host (your machine or cloud VM)
3. Docker Container
- Entrypoint: `adk api_server` → FastAPI application
- Configuration: .env (mapped via `--env-file`)
- Code: app/agent.py (defines endpoints & GenAI calls)
- Dependencies: Python runtime + libraries (requirements.txt)
4. External Service: Google GenAI API or Vertex AI endpoint
b. Interactions:
1. Client → HTTP request → FastAPI endpoint
2. FastAPI parses request, loads API key from environment
3. Agent logic invokes Google’s ADK SDK over HTTPS
4. Google GenAI or Vertex AI returns response
5. FastAPI returns results to client

##### Architectural Patterns & Design Principles
- Microservice: Stateless service behind a single HTTP interface.
- 12-factor app: Config via environment variables; logs to stdout/stderr.
- Containerization: Isolate runtime, dependencies, and deployment.
- Single responsibility: `app/agent.py` solely handles request routing and SDK calls.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Global external client
    Client["Client / SwaggerUI"]:::external

    %% Docker host and container
    subgraph "Docker Host"
        direction TB
        HostPort["Host Port 8000"]:::internal

        subgraph "Docker Container"
            direction TB
            FastAPI["FastAPI Server\n(adk api_server)"]:::internal
            EnvFile[".env"]:::config
            EnvTemplate[".env.template"]:::config
            Dependencies["requirements.txt"]:::config
            DockerfileNode["Dockerfile"]:::config
            Readme["README.md"]:::config
            Gitignore[".gitignore"]:::config
            License["LICENSE"]:::config
            Agent["app/agent.py"]:::internal
            Init["app/__init__.py"]:::internal
        end
    end

    %% External AI service
    GoogleApi["Google GenAI / Vertex AI API"]:::external

    %% Connections
    Client -->|"HTTP POST/GET\n(port 8000)"| HostPort
    HostPort -->|"forwards to\ncontainer port 8000"| FastAPI
    FastAPI -->|"loads API key\nfrom .env"| EnvFile
    FastAPI -->|"invokes SDK over HTTPS"| GoogleApi
    GoogleApi -->|"returns AI response"| FastAPI
    FastAPI -->|"HTTP response"| Client

    %% Click Events
    click Agent "https://github.com/liuyuwei/google-adk-server-example/blob/main/app/agent.py"
    click Init "https://github.com/liuyuwei/google-adk-server-example/blob/main/app/__init__.py"
    click DockerfileNode "https://github.com/liuyuwei/google-adk-server-example/tree/main/Dockerfile"
    click EnvTemplate "https://github.com/liuyuwei/google-adk-server-example/blob/main/.env.template"
    click Dependencies "https://github.com/liuyuwei/google-adk-server-example/blob/main/requirements.txt"
    click Readme "https://github.com/liuyuwei/google-adk-server-example/blob/main/README.md"
    click Gitignore "https://github.com/liuyuwei/google-adk-server-example/blob/main/.gitignore"
    click License "https://github.com/liuyuwei/google-adk-server-example/tree/main/LICENSE"

    %% Styles
    classDef internal fill:#D6E5FF,stroke:#4F79FF,color:#000
    classDef external fill:#D4EDDA,stroke:#28A745,color:#000
    classDef config fill:#FFF3CD,stroke:#FFC107,color:#000
```
