# dawnjo123/ai-agent-builder architecture

> Architecture diagram of the GitHub repository dawnjo123/ai-agent-builder, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dawnjo123/ai-agent-builder
- Repository: https://github.com/dawnjo123/ai-agent-builder

## Overview

##### What this project is (type + purpose)

This is a **small backend-only REST API** (single service) that acts as an **“AI Agent Builder”**:

- Clients call **`POST /generate_agent`** with a natural-language “query”.
- The service uses an **LLM provider (Groq or OpenRouter)** to **generate an agent definition** (custom system prompt + chosen tools).
- Clients then call **`GET /run_agent/<agent_id>`** to execute the agent, which **invokes a set of tools** (scrape web, summarize PDFs, send email, post to Twitter, log to file).
- Agent configs are retrievable via **`GET /all_agents`**.

- **API layer (Flask app)**
- **Agent generation / orchestration**
- **LLM provider integration**
- **Tool plugins** (and which ones are real vs mocked)
- **State/storage** for agent definitions + log file output
- **External systems** (websites, LLM APIs)

##### File structure → architectural components

From the tree:

- **`app.py`**
- Main entry point: defines REST endpoints, initializes the LLM client, builds/executes agents, routes requests.
- **`tools/` package**
- **`web_scraper.py`**: real network calls (requests + BeautifulSoup)
- **`pdf_summarizer.py`**: reads PDFs from `uploads/` path (not in tree, but described)
- **`email_sender.py`**: mocked (prints)
- **`twitter_tool.py`**: mocked (prints)
- **`file_logger.py`**: real filesystem write (e.g., `agent_logs.txt`)
- **`requirements.txt`**
- **`Agent Builder APIs.postman_collection.json`**
- **`.env` (implied by README)**
- Runtime config: API keys and base URL.

Key architectural implication: **monolith service** with a **tool-plugin style module layout**.

##### README → runtime interactions and boundaries

Important details to reflect:

- **Dual LLM support**
- Groq is “primary”, OpenRouter is optional toggle in `app.py`.
- Both are **external SaaS dependencies**.
- **Tools differ by integration fidelity**
- Real: Web Scraper, File Logger, LLM calls
- Mocked: Email Sender, Twitter Tool
- PDF summarizer is “real-ish” locally (reads from uploads path), but no external storage service is shown.
- **No explicit database**

- Shows the API service as a container and its external dependencies.
- This is what stakeholders use to understand the system at a glance.

- Shows `app.py` split into logical components: routing/controllers, agent factory, execution engine, tool interfaces, tool implementations.
- This is what engineers use to reason about change impact, testing, and extensibility.

##### Main components

**External Actors / Clients**
- “API Client” (Postman, frontend, other service)

**API Service (single process)**
- Flask API / Router (endpoints)
- Agent Builder (LLM prompt construction + tool selection)
- Agent Registry (in-memory store of agents: id → {name, query, prompt, tools})
- Agent Runner / Orchestrator (executes tool calls in a workflow)
- Tool Interface / Dispatcher (maps tool names to implementations)

**Tool Implementations (`tools/*`)**
- Web Scraper (HTTP GET → parse HTML)
- PDF Summarizer (read PDFs from local `uploads/` → summarize via LLM or internal logic; depends on code)
- Email Sender (mock; console output)
- Twitter Tool (mock; console output)
- File Logger (write to `agent_logs.txt`)

**External Services**
- Groq API (LLM)
- OpenRouter API (LLM)
- Target Websites (for scraping)

**Data Stores / Artifacts**
- Local filesystem:
- `agent_logs.txt`
- `uploads/` directory (PDF inputs)
- Environment variables / `.env` (configuration source)

##### API → Client (agent_id, tools, prompt)

- “Natural language query”
- “LLM prompt → tool selection”
- “Agent config persisted (in-memory)”

##### Tools may call
- Web Scraper → External Website (HTTP)
- PDF Summarizer → Local uploads/ (read) and possibly → LLM Provider (if it summarizes via LLM)
- File Logger → Local filesystem write

##### Get all agents (`GET /all_agents`)
- Client → `/all_agents`
- Flask → Agent Registry → returns list

##### Architectural patterns/design principles to highlight (project-specific)

- **State management**: no DB present → likely in-memory registry. Mark as a limitation and a replaceable component (future: Redis/Postgres).

##### Required elements
- e.g., “Flask API (app.py)”, “Agent Registry (in-memory)”, “Groq LLM API”
- Blue rectangles: internal components (within your service boundary)
- Orange clouds: external services (Groq/OpenRouter, websites)

- “AI Agent Builder Service (Python/Flask)” boundary containing:
- Router, Builder, Runner, Registry, Tools
- Outside boundary:
- Clients
- LLM providers
- Websites
- (Optional) Console/Stdout as a sink for mocked tools

##### Don’t overthink it: maximize component separation

For this project, “best and most accurate” means you **split the monolith into explicit logical components** even if they live in one file:

- Routes/Controllers
- Agent lifecycle management (create/store/list)
- Execution engine
- Tool interface + concrete tools
- External provider adapters (Groq/OpenRouter)
- Storage artifacts (uploads, logs)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =========================================================
    %% Top: Context / Container view
    %% =========================================================
    Client["API Client (Postman/Other)"]:::client

    subgraph "AI Agent Builder Service (Python/Flask)"
        API["Flask REST API (Routes/Controllers)"]:::api

        subgraph "Core Components"
            Builder["Agent Builder (Prompt + Tool Selection)"]:::component
            Runner["Agent Runner / Orchestrator"]:::component
            Registry[("Agent Registry (In-memory)")]:::store
            Dispatcher["Tool Dispatcher (Tool Interface)"]:::component

            subgraph "LLM Integration"
                LLMClient["LLM Client (Provider Abstraction)"]:::component
                Groq["Groq Provider Adapter"]:::provider
                OpenRouter["OpenRouter Provider Adapter (Optional)"]:::provider
            end

            subgraph "Tool Plugins (tools/*)"
                WebScraper["Web Scraper Tool (Real: HTTP + HTML parse)"]:::tool
                PDFSum["PDF Summarizer Tool (Local read; may use LLM)"]:::tool
                EmailTool["Email Sender Tool (Mock/Stub)"]:::toolmock
                TwitterTool["Twitter Tool (Mock/Stub)"]:::toolmock
                FileLogger["File Logger Tool (Real: FS write)"]:::tool
            end
        end

        EnvCfg[(".env / Environment Variables (Runtime Config)")]:::config
        Req["Dependencies (requirements.txt)"]:::artifact
        Readme["Docs (README.md)"]:::artifact
    end

    GroqAPI["Groq LLM API (External SaaS)"]:::external
    OpenRouterAPI["OpenRouter LLM API (External SaaS)"]:::external
    Websites["Target Websites (External)"]:::external
    UploadsDir[("Local Filesystem: uploads/ (PDF inputs)")]:::fs
    LogsFile[("Local Filesystem: agent_logs.txt")]:::fs
    Stdout["Console/Stdout (Mock output sink)"]:::external

    %% Context connections
    Client -->|"HTTP REST"| API
    API -->|"reads config"| EnvCfg
    API -->|"uses libs"| Req
    API -->|"reference/usage"| Readme

    %% =========================================================
    %% Main flows (vertical emphasis)
    %% =========================================================
    %% POST /generate_agent
    API -->|"POST /generate_agent (query)"| Builder
    Builder -->|"build prompt + select tools"| LLMClient
    LLMClient -->|"call (primary)"| Groq
    LLMClient -.->|"call (optional toggle)"| OpenRouter
    Groq -->|"HTTPS"| GroqAPI
    OpenRouter -.->|"HTTPS"| OpenRouterAPI
    LLMClient -->|"system prompt + tool list"| Builder
    Builder -->|"persist agent config (UUID)"| Registry
    API -->|"returns agent_id + config"| Client

    %% GET /all_agents
    API -->|"GET /all_agents"| Registry
    Registry -->|"list agents"| API

    %% GET /run_agent/<agent_id>
    API -->|"GET /run_agent/{id}"| Registry
    Registry -->|"agent config"| API
    API -->|"execute agent"| Runner
    Runner -->|"invoke tools"| Dispatcher

    %% Tool dispatch
    Dispatcher -->|"tool call"| WebScraper
    Dispatcher -->|"tool call"| PDFSum
    Dispatcher -->|"tool call"| FileLogger
    Dispatcher -->|"tool call"| EmailTool
    Dispatcher -->|"tool call"| TwitterTool

    %% Tool side effects / integrations
    WebScraper -->|"HTTP GET"| Websites
    PDFSum -->|"read PDF(s)"| UploadsDir
    PDFSum -.->|"optional summarize via LLM"| LLMClient
    FileLogger -->|"append/write"| LogsFile
    EmailTool -->|"print (mock)"| Stdout
    TwitterTool -->|"print (mock)"| Stdout

    Runner -->|"final output"| API
    API -->|"HTTP response"| Client

    %% =========================================================
    %% Click events (from component mapping)
    %% =========================================================
    click API "https://github.com/dawnjo123/ai-agent-builder/blob/master/app.py"
    click Builder "https://github.com/dawnjo123/ai-agent-builder/blob/master/app.py"
    click Runner "https://github.com/dawnjo123/ai-agent-builder/blob/master/app.py"
    click Registry "https://github.com/dawnjo123/ai-agent-builder/blob/master/app.py"
    click LLMClient "https://github.com/dawnjo123/ai-agent-builder/blob/master/app.py"

    click Dispatcher "https://github.com/dawnjo123/ai-agent-builder/blob/master/tools/__init__.py"
    click WebScraper "https://github.com/dawnjo123/ai-agent-builder/blob/master/tools/web_scraper.py"
    click PDFSum "https://github.com/dawnjo123/ai-agent-builder/blob/master/tools/pdf_summarizer.py"
    click EmailTool "https://github.com/dawnjo123/ai-agent-builder/blob/master/tools/email_sender.py"
    click TwitterTool "https://github.com/dawnjo123/ai-agent-builder/blob/master/tools/twitter_tool.py"
    click FileLogger "https://github.com/dawnjo123/ai-agent-builder/blob/master/tools/file_logger.py"

    click Client "https://github.com/dawnjo123/ai-agent-builder/blob/master/Agent Builder APIs.postman_collection.json"
    click Req "https://github.com/dawnjo123/ai-agent-builder/blob/master/requirements.txt"
    click Readme "https://github.com/dawnjo123/ai-agent-builder/blob/master/README.md"

    %% =========================================================
    %% Styles
    %% =========================================================
    classDef client fill:#E8F1FF,stroke:#1F4B99,stroke-width:1.5px,color:#0B1F44
    classDef api fill:#CFE8FF,stroke:#1D4ED8,stroke-width:2px,color:#0B1F44
    classDef component fill:#D9F0FF,stroke:#2563EB,stroke-width:1.5px,color:#0B1F44
    classDef tool fill:#EFE6FF,stroke:#6D28D9,stroke-width:1.5px,color:#1E0A3C
    classDef toolmock fill:#F7E8FF,stroke:#A21CAF,stroke-width:1.5px,color:#2A0A2A
    classDef provider fill:#FFE6CC,stroke:#C2410C,stroke-width:1.5px,color:#3A1A00
    classDef external fill:#FFE7D6,stroke:#9A3412,stroke-width:1.5px,color:#3A1A00
    classDef store fill:#E5E7EB,stroke:#374151,stroke-width:1.5px,color:#111827
    classDef fs fill:#E2E8F0,stroke:#334155,stroke-width:1.5px,color:#0F172A
    classDef config fill:#ECFDF5,stroke:#059669,stroke-width:1.5px,color:#064E3B
    classDef artifact fill:#F3F4F6,stroke:#6B7280,stroke-width:1.2px,color:#111827
```
