# shdhumale/app architecture

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

- Interactive diagram: https://gitdiagram.com/shdhumale/app
- Repository: https://github.com/shdhumale/app

## Overview

##### Project Type and Purpose
- This is an open-source Python “toolkit” or demo suite for the Google Accessory Development Kit (ADK).
- It provides a core ADK‐agent implementation plus multiple “flavours” (examples) illustrating different use cases (custom writing agents, long‐running agents, weather examples, REST API clients/servers, etc.).

##### File Structure
- Top‐level folder contains a variety of example scripts (e.g., `SiddhuCustomWritingAgent.py`, `longAgent.py`, `weatherExample.py`, `my_client.py`, `my_server.py`, `restapi-mcp-client.py`, etc.).
- `app/` folder houses the canonical ADK agent implementation:
- app/agent.py – core agent logic
- app/.env – environment variables for ADK configuration
- app/__init__.py – module indicator
- `.env` files at both root and app level configure credentials, ports, and other settings.
- No monolithic web frontend; this is purely a backend/demo⎯networked Python scripts communicating via sockets or REST.

##### Extract Key Insights from the README
- Confirms multiple “flavours” of a Google ADK agent.
- Emphasizes modular structure for experimentation.
- Mentions no GUI or mobile code here—pure Python.
- Dependencies: Python 3+, standard libraries, Google ADK documentation.

##### Main Components
a. Core Agent Library
– app/agent.py with its configuration (.env)
b. Example Agent Flavours
– custom writing (`SiddhuCustomWritingAgent.py`)
– long-running agent (`longAgent.py`, `humanLongAgent.py`)
– session-based agent (`sessionSiddhu.py`, `weatherSessionExample.py`)
– weather data example (`weatherExample.py`)
c. Networking Layers / External Interfaces
– Socket‐based client/server (`my_client.py` ↔ `my_server.py`)
– SSEMCP protocol connectors (`connetSSEMCPServer.py`)
– REST APIs for MCP (`restapi-mcp-client.py` ↔ `restapi-mcp-server.py` and `restapi-mcp-adk-*`)
d. External Services
– Google ADK host (Android accessory)
– External data source (e.g., weather API)
e. Configuration Store
– .env files (root and app)

##### Relationships and Data Flows
- All example scripts import or instantiate the core agent from `app/agent.py`.
- Agents retrieve config from .env and register with the Google ADK host.
- Clients (socket or REST) send requests to their paired servers.
- Servers forward or translate requests to the ADK agent.

##### Architectural Patterns & Design Principles
- Modular “plug-and-play” design: core agent + many independent example wrappers
- Clear separation between network layer (clients/servers) and agent business logic
- Environment/configuration externalization via .env
- Functional decomposition by example use case

## Diagram (Mermaid)

```mermaid
graph TB
    %% Core Agent Library
    subgraph "Core Agent Library"
        Agent["app/agent.py"]:::core
        ConfigApp["app/.env"]:::config
        ConfigRoot[".env"]:::config
    end

    %% Example Wrappers
    subgraph "Custom Writing Agents" 
        SiddhuCU["SiddhuCustomWritingAgent.py"]:::example
        sdCustom["siddhuCustomAgentExample.py"]:::example
        sdCode["siddhuCodeExecution.py"]:::example
    end

    subgraph "Long-Running Agents"
        LongA["longAgent.py"]:::example
        HumanLong["humanLongAgent.py"]:::example
    end

    subgraph "Session-Based Agents"
        SessS["sessionSiddhu.py"]:::example
        WeatherSess["weatherSessionExample.py"]:::example
        SessionStore(["Session Store"]):::external
    end

    subgraph "Weather Agents"
        WeatherEx["weatherExample.py"]:::example
        WeatherAPI(["External Weather API"]):::external
    end

    subgraph "Socket-Based Interfaces"
        Client["my_client.py"]:::network
        Server["my_server.py"]:::network
    end

    subgraph "SSEMCP Protocol Connector"
        SSEMCP["connetSSEMCPServer.py"]:::network
    end

    subgraph "REST API MCP Connectors"
        RestClient["restapi-mcp-client.py"]:::network
        RestServer["restapi-mcp-server.py"]:::network
        AdkClient["restapi-mcp-adk-client.py"]:::network
        AdkServer["restapi-mcp-adk-server.py"]:::network
    end

    %% External Systems
    ADKHost(["Google ADK Host"]):::external

    %% Relationships: Examples use Core Agent
    SiddhuCU -->|"imports"| Agent
    sdCustom -->|"imports"| Agent
    sdCode -->|"imports"| Agent
    LongA -->|"imports"| Agent
    HumanLong -->|"imports"| Agent
    SessS -->|"imports"| Agent
    WeatherSess -->|"imports"| Agent
    WeatherEx -->|"imports"| Agent

    %% Agent to ADK Host
    Agent -->|"ADK communication"| ADKHost

    %% Config arrows
    Agent -->|"reads config"| ConfigApp
    Agent -->|"reads config"| ConfigRoot

    %% Session flows
    SessS -->|"stores session"| SessionStore
    WeatherSess -->|"stores session"| SessionStore

    %% Weather data flow
    WeatherEx -->|"fetches data"| WeatherAPI

    %% Socket interfaces
    Client -->|"TCP Socket"| Server
    Server -->|"forwards to"| Agent

    %% SSEMCP connector
    SSEMCP -->|"SSEMCP"| Agent

    %% REST API flows
    RestClient -->|"HTTP REST"| RestServer
    RestServer -->|"forwards to"| Agent
    AdkClient -->|"HTTP REST"| AdkServer
    AdkServer -->|"forwards to"| Agent

    %% Click Events
    click Agent "https://github.com/shdhumale/app/blob/main/app/agent.py"
    click ConfigApp "https://github.com/shdhumale/app/blob/main/app/.env"
    click ConfigRoot "https://github.com/shdhumale/app/blob/main/.env"
    click SiddhuCU "https://github.com/shdhumale/app/blob/main/SiddhuCustomWritingAgent.py"
    click sdCustom "https://github.com/shdhumale/app/blob/main/siddhuCustomAgentExample.py"
    click sdCode "https://github.com/shdhumale/app/blob/main/siddhuCodeExecution.py"
    click LongA "https://github.com/shdhumale/app/blob/main/longAgent.py"
    click HumanLong "https://github.com/shdhumale/app/blob/main/humanLongAgent.py"
    click SessS "https://github.com/shdhumale/app/blob/main/sessionSiddhu.py"
    click WeatherSess "https://github.com/shdhumale/app/blob/main/weatherSessionExample.py"
    click WeatherEx "https://github.com/shdhumale/app/blob/main/weatherExample.py"
    click Client "https://github.com/shdhumale/app/blob/main/my_client.py"
    click Server "https://github.com/shdhumale/app/blob/main/my_server.py"
    click SSEMCP "https://github.com/shdhumale/app/blob/main/connetSSEMCPServer.py"
    click RestClient "https://github.com/shdhumale/app/blob/main/restapi-mcp-client.py"
    click RestServer "https://github.com/shdhumale/app/blob/main/restapi-mcp-server.py"
    click AdkClient "https://github.com/shdhumale/app/blob/main/restapi-mcp-adk-client.py"
    click AdkServer "https://github.com/shdhumale/app/blob/main/restapi-mcp-adk-server.py"

    %% Legend (via class definitions)
    classDef core fill:#D0E6FA,stroke:#3E8FC7,color:#0B3D91;
    classDef config fill:#E8F4FD,stroke:#B3DCE8,color:#0B3D91;
    classDef example fill:#E6F4EA,stroke:#29A745,color:#145C32;
    classDef network fill:#FFF4E6,stroke:#FFA500,color:#A45100;
    classDef external fill:#F0F0F0,stroke:#AAAAAA,color:#666666;
```
