# kkdai/linebot-adk-stock architecture

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

- Interactive diagram: https://gitdiagram.com/kkdai/linebot-adk-stock
- Repository: https://github.com/kkdai/linebot-adk-stock

## Overview

##### Project Type and Purpose
- This is a backend microservice (no UI) implementing a LINE messaging bot.
- It uses FastAPI to receive webhooks, routes incoming messages to AI-powered agents, calls external AI and data‐fetching services, and replies via the LINE Messaging API.
- The multi-agent design currently includes one “stock_agent” (with a planned general agent), in-memory session management, and function‐calling tools.

##### Top-Level Components
- LINE Platform (Messaging API)
- FastAPI Service (main.py)
- Webhook Receiver
- Runner / Agent Orchestrator
- InMemorySessionService
- Agent Modules (multi_tool_agent/stock_agent.py)
- stock_agent with its tool functions: get_stock_price, get_price_change_percent, get_best_performing
- External Services
- Google ADK (Agent SDK) → Google Gemini API or VertexAI
- yfinance (Yahoo Finance)
- Deployment Artifacts
- Docker container
- Cloud Run (or local via uvicorn / ngrok)

##### Relationships and Data Flow
1. A user sends a text message in LINE → LINE Platform pushes a webhook to your FastAPI endpoint.
2. FastAPI Webhook Receiver authenticates & extracts user ID + message.
3. InMemorySessionService loads/creates session context for that user.
4. Runner inspects the message, selects the root_agent (currently stock_agent).
5. stock_agent invokes one or more tool functions:
– If user asks for a stock price → calls get_stock_price (yfinance)
– If user asks percentage change → calls get_price_change_percent
– If user asks best performer → calls get_best_performing
6. For non‐tool steps or fallback, the agent uses Google ADK → Google Gemini or VertexAI to generate text.
7. Assembled reply is sent back through LINE Messaging API to the user.

##### Architectural Patterns and Principles
- Microservice: independent FastAPI service receiving webhooks.
- Modular Agent Pattern: pluggable agents/tools.
- Function Calling: agents call pure‐function tools for external data.
- Dependency Injection via environment variables and Docker.
- Stateless container with in-memory sessions (can be swapped for Redis in future).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Client
    LINE["LINE Messaging API"]:::external

    %% Deployment Layer
    subgraph "Cloud Run" 
        direction TB
        subgraph "Docker Container"
            direction TB
            ENV["Env Vars\n(ChannelSecret, GOOGLE_API_KEY)"]:::infra
            subgraph "FastAPI Service" 
                direction TB
                WR["Webhook Receiver"]:::internal
                ISS["InMemorySessionService"]:::internal
                ORC["Runner / Orchestrator"]:::internal
            end
            subgraph "Agents" 
                direction TB
                SA["stock_agent"]:::internal
                subgraph "Tools" 
                    direction TB
                    SP["get_stock_price"]:::tool
                    PC["get_price_change_percent"]:::tool
                    BP["get_best_performing"]:::tool
                    click SP "https://github.com/kkdai/linebot-adk-stock/blob/main/multi_tool_agent/stock_agent.py"
                    click PC "https://github.com/kkdai/linebot-adk-stock/blob/main/multi_tool_agent/stock_agent.py"
                    click BP "https://github.com/kkdai/linebot-adk-stock/blob/main/multi_tool_agent/stock_agent.py"
                end
                click SA "https://github.com/kkdai/linebot-adk-stock/blob/main/multi_tool_agent/stock_agent.py"
            end
        end
        click ENV "https://github.com/kkdai/linebot-adk-stock/tree/main/Dockerfile"
        click ENV "https://github.com/kkdai/linebot-adk-stock/tree/main/Procfile"
        click ENV "https://github.com/kkdai/linebot-adk-stock/blob/main/requirements.txt"
        click ENV "https://github.com/kkdai/linebot-adk-stock/blob/main/runtime.txt"
        click WR "https://github.com/kkdai/linebot-adk-stock/blob/main/main.py"
        click ISS "https://github.com/kkdai/linebot-adk-stock/blob/main/main.py"
        click ORC "https://github.com/kkdai/linebot-adk-stock/blob/main/main.py"
    end

    %% External Services
    subgraph "External Services"
        direction TB
        YF["Yahoo Finance (yfinance)"]:::external
        GA["Google ADK (Agent SDK)"]:::external
        GI["Google Gemini / VertexAI"]:::external
    end

    %% Flows
    LINE -->|1. webhook POST| WR
    WR -->|2. load/create session| ISS
    ISS -->|3. orchestrate| ORC
    ORC -->|4. call agent| SA
    SA -->|5a. get price| SP
    SA -->|5b. get change| PC
    SA -->|5c. best performer| BP
    SP -->|fetch data| YF
    PC -->|fetch data| YF
    BP -->|fetch data| YF
    ORC -->|6. call for text| GA
    GA -->|AI call| GI
    ORC -->|7. send reply| LINE

    %% Styles
    classDef internal fill:#D0E6FF,stroke:#0288D1,stroke-width:1px
    classDef external fill:#E0F2F1,stroke:#00796B,stroke-width:1px
    classDef tool fill:#FFF3E0,stroke:#FB8C00,stroke-width:1px
    classDef infra fill:#F5F5F5,stroke:#9E9E9E,stroke-width:1px
```
