# ris3abh/webwiseagent architecture

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

- Interactive diagram: https://gitdiagram.com/ris3abh/webwiseagent
- Repository: https://github.com/ris3abh/webwiseagent

## Overview

##### Project Type and Purpose
- This is a Python-based, modular, AI-powered personal assistant (CLI application) that orchestrates:
- User interaction via `main.py`
- Prompt management (`prompts/`)
- Tooling modules (`utils/`): web scraping, file I/O, retrieval
- LLM calls (OpenAI API via `utils/llm.py`)
- Result storage (“results/” folder + file system)

##### Main Components
a. Frontend / Entry Point
- **main.py**: CLI or script entry, parses user input and coordinates tasks
b. Orchestrator / Agent Core
- Component that applies decision logic (e.g., “Do I need a web search?”)
- References config (`config.py`), uses backoff (retry) utilities
c. Prompt Manager
- `prompts/system_prompts.py` & `prompts/user_prompts.py`
- Supplies structured messages to the LLM
d. Tooling Modules
- **Web Scraper** (`utils/web_scraper.py`): fetches external web data / Google search
- **Retrieval** (`utils/retrival.py`): local RAG functionality
- **File Handler** (`utils/file_handler.py`): read/write docs
- **Backoff Utils** (`utils/backoff_utils.py`): retry logic for API calls
e. LLM Service
- **OpenAI API** accessed through `utils/llm.py`
f. Storage
- **Local file system**: results folder, cached documents, logs
g. External Services
- **Google Search or other web APIs** via scraper
- **OpenAI** (cloud LLM)

##### Interaction & Data Flow
1. User → main.py (CLI)
2. main.py → Orchestrator logic
3. Orchestrator → Prompt Manager (choose system/user prompt)
4. Orchestrator → Tool modules (web_scraper or retrieval) as needed
5. Tool modules → return data → Orchestrator
6. Orchestrator → llm.py (OpenAI API call)
7. llm.py → OpenAI Cloud → llm.py → response → Orchestrator
8. Orchestrator → File Handler (optionally save output)
9. Orchestrator → User (stdout) and results/ (persist)

##### Architectural Patterns & Principles
- **Modular Design**: Each tool is a standalone Python module
- **Separation of Concerns**:
- Prompt logic separated from orchestration
- I/O logic in `utils/file_handler.py`
- External API logic in `utils/llm.py` and `utils/web_scraper.py`
- **RAG Ready**: Show retrieval module inline, ready to merge external knowledge with generation

##### Elements to Include on the Canvas
- **Results Persistence**: show final responses saved under `results/` directory.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Entities
    User["User (CLI)"]
    Main["main.py (Entry & Orchestrator)"]:::core
    Config["config.py"]:::core

    subgraph "Prompt Manager"
        SysP["system_prompts.py"]:::core
        UserP["user_prompts.py"]:::core
    end

    subgraph "Tool Modules"
        WS["Web Scraper"]:::tools
        RET["Retrieval (RAG)"]:::tools
        FH["File Handler"]:::tools
        BO["Backoff Utils"]:::tools
    end

    LLM["llm.py (OpenAI Interface)"]:::tools

    subgraph "External Services"
        Google["Google Search"]:::external
        OpenAI["OpenAI API"]:::external
    end

    Storage["results/ (Persistence)"]:::storage

    %% Connections
    User -->|"input"| Main
    Main -->|"load config"| Config
    Main -->|"choose prompt"| SysP
    Main -->|"choose prompt"| UserP
    Main -->|"if search needed"| WS
    Main -->|"if RAG enabled"| RET
    WS -->|"search results"| Main
    RET -->|"retrieved docs"| Main
    Main -->|"apply retry logic"| BO
    Main -->|"call LLM.generate() "| LLM
    LLM -->|"request"| OpenAI
    OpenAI -->|"response"| LLM
    LLM -->|"LLM response"| Main
    Main -->|"save output"| FH
    FH -->|"writes"| Storage
    Main -->|"outputs"| User

    %% Click Events
    click Main "https://github.com/ris3abh/webwiseagent/blob/main/main.py"
    click Config "https://github.com/ris3abh/webwiseagent/blob/main/config.py"
    click SysP "https://github.com/ris3abh/webwiseagent/blob/main/prompts/system_prompts.py"
    click UserP "https://github.com/ris3abh/webwiseagent/blob/main/prompts/user_prompts.py"
    click WS "https://github.com/ris3abh/webwiseagent/blob/main/utils/web_scraper.py"
    click RET "https://github.com/ris3abh/webwiseagent/blob/main/utils/retrival.py"
    click FH "https://github.com/ris3abh/webwiseagent/blob/main/utils/file_handler.py"
    click BO "https://github.com/ris3abh/webwiseagent/blob/main/utils/backoff_utils.py"
    click LLM "https://github.com/ris3abh/webwiseagent/blob/main/utils/llm.py"
    click Storage "https://github.com/ris3abh/webwiseagent/tree/main/results/"

    %% Styles
    classDef core fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef tools fill:#90EE90,stroke:#333,stroke-width:1px
    classDef external fill:#FFA500,stroke:#333,stroke-width:1px
    classDef storage fill:#D3D3D3,stroke:#333,stroke-width:1px
```
