# qaillc/adk-made-simple architecture

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

- Interactive diagram: https://gitdiagram.com/qaillc/adk-made-simple
- Repository: https://github.com/qaillc/adk-made-simple

## Overview

##### Project Type and Purpose
- This is an open-source sample “agent” toolkit built on Google’s Agent Development Kit (ADK).
- It demonstrates a series of simple agents (Reddit Scout, Async Reddit Scout, Summarizer, Speaker, Coordinator) and how to wire them together into a multi-agent system.

##### High-Level Architecture Analysis
– Top-level “agents/” directory contains five independent agent modules, each with its own agent.py.
– The ADK CLI (adk run / adk web) is the entry point; it discovers and loads a chosen agent package.
– Agents rely on:
- ADK core libraries (Google AI integration)
- Third-party APIs (PRAW for Reddit, Google AI Studio APIs, ElevenLabs TTS, LiteLLM for asynchronous tasks)
– The Coordinator agent orchestrates the sequence: Scout → Summarizer → Speaker.

##### Main Components
A. Developer Environment
- Local filesystem & project code (root, agents/*, .env)
- Environment variables loader (python-dotenv or shell)
- Python virtualenv & pip dependencies (requirements.txt)
B. ADK Runtime
- ADK CLI / web server
- ADK core framework & discovery mechanism
C. Agents (each as a component)
- reddit_scout (fetches Reddit via PRAW → returns messages)
- async_reddit_scout (async version, web view only)
- summarizer (AI-powered summarization via Google AI)
- speaker (TTS via ElevenLabs or LiteLLM)
- coordinator (invokes other agents in sequence, merges results)
D. External Services
- Reddit API (PRAW)
- Google AI Studio API (text generation, summarization)
- ElevenLabs / LiteLLM TTS API
- Optional: monitoring/logging or CLI stdout

##### Relationships & Data Flow
1. The developer runs “adk run <agent_name>” (or “adk web”).
2. ADK CLI loads environment variables, discovers the agent package.
3. The chosen agent invokes external service calls:
– Scout agents → Reddit API → raw posts/titles
– Summarizer → Google AI API → condensed text
– Speaker → TTS API → audio output
4. Coordinator → calls Scout → pipes output to Summarizer → pipes to Speaker → final response returned to CLI/web view.

##### Architectural Patterns & Principles
- Modular component structure: each agent is a standalone package.
- Single-responsibility: Scout only fetches, Summarizer only condenses, Speaker only vocalizes.
- Orchestration via a Coordinator agent, illustrating a simple Microservices or Pipeline pattern.
- Clear separation of concerns: ADK framework vs agent business logic vs external APIs.

##### Essential Elements
- Clear component labels (ADK CLI, each agents/… folder, external APIs)
- Notes on synchronous vs asynchronous paths (for async_reddit_scout via web view)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer
    Developer["Developer"]:::developer

    %% Environment / Config
    subgraph "Environment / Config"
        ENV[".env.example"]:::config
        REQ["requirements.txt"]:::config
        README["README.md"]:::config
    end

    %% ADK Runtime
    CLI["ADK CLI / Runtime"]:::runtime

    %% Agents
    subgraph "Agents" 
        RS["agents/reddit_scout: Fetch Reddit posts"]:::agent
        ARS["agents/async_reddit_scout: Async Reddit posts (Web)"]:::agent
        SUM["agents/summarizer: Summarize text"]:::agent
        SPK["agents/speaker: Text-to-Speech"]:::agent
        COORD["agents/coordinator: Orchestrate pipeline"]:::agent
    end

    %% External Services
    subgraph "External Services"
        RedditAPI["Reddit API (PRAW)"]:::external
        GoogleAI["Google AI Studio API"]:::external
        TTSAPI["ElevenLabs / LiteLLM TTS API"]:::external
    end

    %% Flows
    Developer -->|"runs adk run / adk web"| CLI
    CLI -->|"discovers agents"| RS
    CLI -->|"discovers agents"| ARS
    CLI -->|"discovers agents"| SUM
    CLI -->|"discovers agents"| SPK
    CLI -->|"discovers agents"| COORD

    %% Independent agent flows
    RS -->|"titles list"| RedditAPI
    RedditAPI -->|"raw posts"| RS
    ARS -->|"titles list (async)"| RedditAPI
    RedditAPI -->|"raw posts"| ARS
    SUM -->|"request text summary"| GoogleAI
    GoogleAI -->|"summary text"| SUM
    SPK -->|"request audio"| TTSAPI
    TTSAPI -->|"audio blob"| SPK

    %% Coordinator pipeline
    COORD -->|"invoke reddit_scout"| RS
    RS -->|"posts data"| COORD
    COORD -->|"invoke summarizer"| SUM
    SUM -->|"summary text"| COORD
    COORD -->|"invoke speaker"| SPK
    SPK -->|"audio blob"| COORD
    COORD -->|"final response"| CLI

    %% Click Events
    click ENV "https://github.com/qaillc/adk-made-simple/blob/main/.env.example"
    click REQ "https://github.com/qaillc/adk-made-simple/blob/main/requirements.txt"
    click README "https://github.com/qaillc/adk-made-simple/blob/main/README.md"
    click RS "https://github.com/qaillc/adk-made-simple/blob/main/agents/reddit_scout/agent.py"
    click RS "https://github.com/qaillc/adk-made-simple/blob/main/agents/reddit_scout/__init__.py"
    click ARS "https://github.com/qaillc/adk-made-simple/blob/main/agents/async_reddit_scout/agent.py"
    click ARS "https://github.com/qaillc/adk-made-simple/blob/main/agents/async_reddit_scout/__init__.py"
    click SUM "https://github.com/qaillc/adk-made-simple/blob/main/agents/summarizer/agent.py"
    click SUM "https://github.com/qaillc/adk-made-simple/blob/main/agents/summarizer/__init__.py"
    click SPK "https://github.com/qaillc/adk-made-simple/blob/main/agents/speaker/agent.py"
    click SPK "https://github.com/qaillc/adk-made-simple/blob/main/agents/speaker/__init__.py"
    click COORD "https://github.com/qaillc/adk-made-simple/blob/main/agents/coordinator/agent.py"
    click COORD "https://github.com/qaillc/adk-made-simple/blob/main/agents/coordinator/__init__.py"

    %% Styles
    classDef developer fill:#e0f7fa,stroke:#006064,color:#006064
    classDef config fill:#e8f5e9,stroke:#2e7d32,color:#2e7d32
    classDef runtime fill:#bbdefb,stroke:#0d47a1,color:#0d47a1
    classDef agent fill:#c5cae9,stroke:#1a237e,color:#1a237e
    classDef external fill:#ffe0b2,stroke:#e65100,color:#e65100
```
