# devgomesai/web-agent architecture

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

- Interactive diagram: https://gitdiagram.com/devgomesai/web-agent
- Repository: https://github.com/devgomesai/web-agent

## Overview

##### Project type and purpose
- This is a standalone CLI tool (Python package) that performs AI-driven web searches, analyzes the results, and displays a rich, formatted response in the terminal.
- It leverages Brave Search for crawling the web, and one or more AI providers (OpenAI GPT models or Google Gemini) for analysis.

##### File structure
- Top-level files:
- `cli_web_agent.py` – the entry point for the CLI (likely powered by Typer)
- `pyproject.toml` – build, dependencies, and packaging configuration
- `.claude/settings.local.json` – local settings for Claude agent framework
- Lock files (`uv.lock`) and environment/version config (`.python-version`)
- No separate “frontend” or “backend” folders: this is a single Python module/package.

##### README insights
- Core workflow:
1. Query Processing
2. Web Search (Brave API)
3. AI Analysis (OpenAI/Google)
4. Formatting & Display (Rich + Typer CLI)
5. Cost & Token Tracking
- Key dependencies: PydanticAI (agent framework), Typer (CLI parsing), Rich (UI), Brave Search API, OpenAI/Google AI.

##### Main components
a. CLI Interface (Typer + cli_web_agent.py)
b. Configuration Manager (env variables, `.env`, Pydantic models)
c. Query Processor Module (parses and normalizes user input)
d. Web Search Service Adapter (Brave Search API client)
e. AI Analysis Service Adapter (OpenAI / Google AI clients)
f. Analysis Orchestrator (coordinates search + AI calls)
g. Output Formatter (Rich panels, tables, progress bars)
h. Cost & Token Tracker (records usage, estimates cost)
i. Packaging / Build (pyproject.toml, build artifacts)
j. External Services (Brave Search, OpenAI, Google AI)

##### Relationships & interactions
- CLI → Query Processor → Analysis Orchestrator
- Analysis Orchestrator ↔ Web Search Service Adapter
- Analysis Orchestrator ↔ AI Analysis Service Adapter
- Analysis Orchestrator → Cost & Token Tracker
- Analysis Orchestrator → Output Formatter → CLI stdout
- Configuration Manager injects API keys and model settings into Service Adapters and Query Processor
- Packaging / Build is orthogonal – shows how the tool is distributed

##### Architectural Patterns & Design Principles
- Modular adapters for external services, enabling swapping AI providers
- Separation of concerns: parsing, searching, analyzing, formatting, and tracking are distinct modules
- Dependency injection via environment/config manager
- Single‐process, synchronous orchestration (could evolve to async if needed)

##### Putting it all together
- Related components inside a boundary titled “Web Agent CLI Application.”
- At the bottom or side, show “Packaging & Distribution” (pyproject.toml → dist/*.whl, .tar.gz).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Web Agent CLI Application"
        CLI["CLI Interface (Typer)"]:::internal
        QP["Query Processor Module"]:::internal
        AO["Analysis Orchestrator"]:::internal
        WSA["Web Search Service Adapter"]:::internal
        AIA["AI Analysis Service Adapter"]:::internal
        CTT["Cost & Token Tracker"]:::internal
        OF["Output Formatter (Rich)"]:::ui

        subgraph "Configuration Manager"
            CL["Local Settings"]:::config
            PV["Version Config"]:::config
            PJ["Dependency Config"]:::config
        end
    end

    CLI -->|"user command"| QP
    QP -->|"normalized query"| AO
    AO -->|"search query"| WSA
    WSA -->|"search results"| AO
    AO -->|"analysis prompt"| AIA
    AIA -->|"analysis result"| AO
    AO -->|"usage data"| CTT
    AO -->|"formatted data"| OF
    OF -->|"formatted output"| CLI

    CL -.-> QP
    PV -.-> QP
    PJ -.-> WSA
    PJ -.-> AIA

    subgraph "External Services"
        BR["Brave Search API"]:::external
        OA["OpenAI API"]:::external
        GA["Google AI API"]:::external
    end

    WSA -->|"HTTP request"| BR
    AIA -->|"HTTP request"| OA
    AIA -->|"HTTP request"| GA

    subgraph "Packaging & Distribution"
        PPJ["pyproject.toml"]:::build
        UV["uv.lock"]:::build
        RD["README.md"]:::build
        LIC["LICENSE"]:::build
    end

    PPJ -.-> CLI
    UV -.-> CLI
    RD -.-> CLI
    LIC -.-> CLI

    click CLI "https://github.com/devgomesai/web-agent/blob/main/cli_web_agent.py"
    click QP "https://github.com/devgomesai/web-agent/blob/main/cli_web_agent.py"
    click WSA "https://github.com/devgomesai/web-agent/blob/main/cli_web_agent.py"
    click AIA "https://github.com/devgomesai/web-agent/blob/main/cli_web_agent.py"
    click AO "https://github.com/devgomesai/web-agent/blob/main/cli_web_agent.py"
    click OF "https://github.com/devgomesai/web-agent/blob/main/cli_web_agent.py"
    click CTT "https://github.com/devgomesai/web-agent/blob/main/cli_web_agent.py"
    click CL "https://github.com/devgomesai/web-agent/blob/main/.claude/settings.local.json"
    click PV "https://github.com/devgomesai/web-agent/blob/main/.python-version"
    click PJ "https://github.com/devgomesai/web-agent/blob/main/pyproject.toml"
    click PPJ "https://github.com/devgomesai/web-agent/blob/main/pyproject.toml"
    click UV "https://github.com/devgomesai/web-agent/blob/main/uv.lock"
    click RD "https://github.com/devgomesai/web-agent/blob/main/README.md"
    click LIC "https://github.com/devgomesai/web-agent/tree/main/LICENSE"

    classDef internal fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef config fill:#d5f5e3,stroke:#333,stroke-width:1px
    classDef external fill:#f9e79f,stroke:#333,stroke-width:1px
    classDef ui fill:#d2b4de,stroke:#333,stroke-width:1px
    classDef build fill:#f2f3f4,stroke:#333,stroke-dasharray: 5 5,stroke-width:1px
```
