# mohitbhimrajka/adk-copilot architecture

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

- Interactive diagram: https://gitdiagram.com/mohitbhimrajka/adk-copilot
- Repository: https://github.com/mohitbhimrajka/adk-copilot

## Overview

##### Project Type and Purpose
- This is an open-source framework (ADK Copilot) built on the Google Agent Development Kit (ADK) that orchestrates a team of specialized AI agents to automate end-to-end workflows—primarily the software development lifecycle.
- It is not a traditional frontend-backend web app; rather, it is a modular AI orchestration system with pluggable “sub-agents,” custom tools, data sources, evaluation suites, and deployment scripts.

##### File Structure
- Top-level directories:
- adk_copilot/
– agent.py         → The central orchestrator agent (state machine)
– prompts.py       → Shared prompt templates
– entities/        → Pydantic models (SupportTicket, etc.)
– sub_agents/      → Six specialist agents (analysis, retrieval, generation, review, problem solving)
- data/              → Knowledge base materials and sample database CSV
- scripts/           → Data preparation, doc scraping, RAG setup, PDF conversion
- deployment/        → Cloud Run and Vertex AI Agent Engine deployment entry points
- eval/              → Test harness for conversation-based evaluation
- setup_environment.sh → Bootstrap script for provisioning GCP resources
- Configuration files: .env.example, pyproject.toml, .gitignore
- CI/infra: deployment/*.sh & .py, setup_environment.sh

##### Extract Key Architectural Insights from the README
- Orchestrator as a stateful finite state machine with discrete lifecycle states (`New` → `Analyzing` → `AwaitingConfirmation` → `Generating` → `Reviewing`).
- Six specialist sub-agents, each with a narrow responsibility:
1. ticket_analysis_agent
2. knowledge_retrieval_agent (Vertex AI RAG)
3. db_retrieval_agent (BigQuery vector search)
5. code_reviewer_agent (style guide QA)
6. problem_solver_agent
- Custom tools bridge to external systems:
- GCS file reader for multi-modal inputs
- Vertex AI RAG for documentation search
- BigQuery for historical ticket search
- Deployment targets: Google Cloud Run and Vertex AI Agent Engine

##### Main Components
- User Interface Layer
- ADK CLI/Web UI (adk web)
- Orchestrator Agent
- State machine logic (agent.py)
- Prompts engine
- Tooling Layer
- FileReaderTool (GCS)
- BigQuerySearchTool
- RAGTool (Vertex AI)
- MermaidRenderer
- Data Sources
- GCS bucket (knowledge_base documents)
- BigQuery dataset (resolved_tickets.csv)
- External Services
- Google Cloud Storage
- BigQuery
- Vertex AI RAG Engine
- Deployment & Infrastructure
- setup_environment.sh (IaC)
- Cloud Run service
- Vertex AI Agent Engine
- Evaluation Suite
- eval/test_eval.py

##### Relationships and Interactions
- Sub-Agents → Tools → External Services/Data Sources (GCS, BigQuery, Vertex AI)
- code_generator_agent → Generated Code → code_reviewer_agent → Approved Code → User
- Deployment scripts triggered by setup_environment.sh → provision infra → deploy Cloud Run & Agent Engine
- eval suite invokes orchestrator endpoints for automated testing

##### Architectural Patterns and Principles
- State Machine Workflow: clear lifecycle transitions in the orchestrator
- Modular, Pluggable Sub-Agents: each agent isolated, interchangeable, single-responsibility
- Tool Abstraction Layer: decouples sub-agents from external systems
- Event-Driven/Message-Passing: agents communicate via structured messages/entities

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% UI Layer
    subgraph "UI/UX Layer"
        direction TB
        UI["ADK CLI / Web UI"]:::ui
    end

    %% Orchestrator
    subgraph "Orchestrator"
        direction TB
        Orchestrator[/"Orchestrator Agent\nState Machine"/]:::orchestrator
        Prompts["Prompt Templates Engine"]:::orchestrator
    end

    %% Specialist Agents
    subgraph "Specialist Agents"
        direction TB
        TA["Ticket Analysis Agent"]:::subagent
        KR["Knowledge Retrieval Agent"]:::subagent
        DBR["DB Retrieval Agent"]:::subagent
        CG["Code Generator Agent"]:::subagent
        CR["Code Reviewer Agent"]:::subagent
        PS["Problem Solver Agent"]:::subagent
    end

    %% Tools Layer
    subgraph "Tool Abstraction Layer"
        direction TB
        FR["GCS File Reader Tool"]:::tool
        BT["BigQuery Search Tool"]:::tool
        RT["Vertex AI RAG Tool"]:::tool
        MR["Mermaid Renderer"]:::tool
    end

    %% Data Sources
    subgraph "Data Sources"
        direction TB
        GCS[(GCS Bucket\nKnowledge Base)]:::data
        BQ[(BigQuery Dataset\nResolved Tickets)]:::data
    end

    %% External Services
    subgraph "External Services"
        direction TB
        CloudStorage["Google Cloud Storage"]:::external
        BigQueryService["BigQuery"]:::external
        VertexRAG["Vertex AI RAG Engine"]:::external
    end

    %% Deployment & Infra
    subgraph "Deployment & Infrastructure"
        direction TB
        IaC["Infrastructure Bootstrap\n(setup_environment.sh)"]:::infra
        CRD["Cloud Run Deployment"]:::infra
        VAE["Vertex AI Agent Engine\nDeployment"]:::infra
    end

    %% Evaluation Suite
    subgraph "Evaluation Suite"
        direction TB
        EvalSuite["Test Harness\n(eval/test_eval.py)"]:::eval
    end

    %% Connections
    UI -->|"user command"| Orchestrator
    Orchestrator -->|"load prompts"| Prompts
    Orchestrator -->|"Assign Task"| TA
    Orchestrator -->|"Assign Task"| KR
    Orchestrator -->|"Assign Task"| DBR
    Orchestrator -->|"Assign Task"| CG
    Orchestrator -->|"Assign Task"| CR
    Orchestrator -->|"Assign Task"| PS

    TA -->|"analyze ticket"| FR
    KR -->|"fetch docs"| RT
    DBR -->|"vector search"| BT
    CG -->|"generate diagram"| MR
    CG -->|"generate code"| CR
    CR -->|"review code"| Orchestrator
    PS -->|"solve problem"| Orchestrator

    FR -->|"read files"| CloudStorage
    RT -->|"RAG query"| VertexRAG
    BT -->|"BigQuery query"| BigQueryService
    MR -->|"render PNG"| UI

    IaC --> CRD
    IaC --> VAE

    EvalSuite -->|"invoke endpoints"| UI
    EvalSuite --> Orchestrator

    %% Click Events
    click Orchestrator "https://github.com/mohitbhimrajka/adk-copilot/blob/main/adk_copilot/agent.py"
    click Prompts "https://github.com/mohitbhimrajka/adk-copilot/blob/main/adk_copilot/prompts.py"
    click TA "https://github.com/mohitbhimrajka/adk-copilot/blob/main/adk_copilot/sub_agents/ticket_analysis/agent.py"
    click KR "https://github.com/mohitbhimrajka/adk-copilot/blob/main/adk_copilot/sub_agents/knowledge_retrieval/agent.py"
    click DBR "https://github.com/mohitbhimrajka/adk-copilot/blob/main/adk_copilot/sub_agents/db_retrieval/agent.py"
    click CG "https://github.com/mohitbhimrajka/adk-copilot/blob/main/adk_copilot/sub_agents/code_generator/agent.py"
    click CR "https://github.com/mohitbhimrajka/adk-copilot/blob/main/adk_copilot/sub_agents/code_reviewer/agent.py"
    click PS "https://github.com/mohitbhimrajka/adk-copilot/blob/main/adk_copilot/sub_agents/problem_solver/agent.py"
    click FR "https://github.com/mohitbhimrajka/adk-copilot/blob/main/adk_copilot/tools/file_reader_tool.py"
    click BT "https://github.com/mohitbhimrajka/adk-copilot/blob/main/adk_copilot/tools/tools.py"
    click RT "https://github.com/mohitbhimrajka/adk-copilot/blob/main/adk_copilot/tools/tools.py"
    click MR "https://github.com/mohitbhimrajka/adk-copilot/blob/main/adk_copilot/tools/tools.py"
    click GCS "https://github.com/mohitbhimrajka/adk-copilot/tree/main/data/knowledge_base/"
    click BQ "https://github.com/mohitbhimrajka/adk-copilot/blob/main/data/resolved_tickets.csv"
    click IaC "https://github.com/mohitbhimrajka/adk-copilot/blob/main/setup_environment.sh"
    click CRD "https://github.com/mohitbhimrajka/adk-copilot/blob/main/deployment/deploy_cloud_run.sh"
    click VAE "https://github.com/mohitbhimrajka/adk-copilot/blob/main/deployment/deploy_agent_engine.py"
    click EvalSuite "https://github.com/mohitbhimrajka/adk-copilot/blob/main/eval/test_eval.py"

    %% Styles
    classDef ui fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef orchestrator fill:#0B6623,stroke:#044f1a,color:#ffffff;
    classDef subagent fill:#A8E6CF,stroke:#4CAF50,color:#344E41;
    classDef tool fill:#FFD8B1,stroke:#FF8C00,color:#663300;
    classDef data fill:#E6E6FA,stroke:#8A2BE2,color:#4B0082;
    classDef external fill:#E0FFFF,stroke:#00CED1,color:#008B8B;
    classDef infra fill:#F0F0F0,stroke:#A9A9A9,color:#696969;
    classDef eval fill:#FFFACD,stroke:#FFD700,color:#B8860B;
```
