# venopyx/shellsense architecture

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

- Interactive diagram: https://gitdiagram.com/venopyx/shellsense
- Repository: https://github.com/venopyx/shellsense

## Overview

##### Main Components Overview

a) Core System Components:
- CLI Interface (Entry Point)
- AI Provider System
- Tools Management
- Configuration Management
- Utilities Layer

b) External Services:
- OpenAI API
- Gemini API
- Cloudflare AI
- Various Web Services (GitHub, Stock APIs, etc.)

##### Detailed Component Breakdown

A. User Interface Layer:
- CLI interface (__main__.py) as the entry point
- It to the Tool Manager which orchestrates all operations

B. AI Provider System:
- Specialized providers:
- OpenAI Provider
- Gemini Provider
- Cloudflare Provider
- FriendlyAIResponse handler

C. Tools Layer:
- Tools into categories:
- Code Tools (code_generator.py)
- Data Tools (github.py, stock.py, wikipedia_search.py)
- Language Tools (translator.py)
- Media Tools (screenshoter.py)
- Shell Tools (command_execution.py)
- Web Tools (crawler.py, producthunt.py, websearch.py)

D. Configuration & Utilities:
- Settings.py managing environment configurations
- Utility services:
- logging_manager.py
- system_context.py
- loading.py

##### Important Details

- Configuration flow showing how environment variables are loaded
- Tool registration and discovery process
- AI provider selection logic
- Error handling pathways
- Asynchronous operations (if any)
- Cache/storage mechanisms

- User Interface    |

- Tool Management    |

- AI Providers       |

- External Services  |

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph Legend
        L1[Core Component]:::core
        L2([External Service]):::external
        L3{Decision Point}:::decision
        L4>Utility]:::utility
    end

    subgraph "User Interface Layer"
        CLI["CLI Interface"]:::core
        click CLI "https://github.com/venopyX/shellsense/blob/main/shellsense/__main__.py"
    end

    subgraph "Tool Management Layer"
        TM["Tool Manager"]:::core
        BT["Base Tool"]:::core
        click TM "https://github.com/venopyX/shellsense/blob/main/shellsense/tools/tool_manager.py"
        click BT "https://github.com/venopyX/shellsense/blob/main/shellsense/tools/base_tool.py"

        subgraph "Code Tools"
            CG["Code Generator"]:::tool
            click CG "https://github.com/venopyX/shellsense/blob/main/shellsense/tools/coder/code_generator.py"
        end

        subgraph "Data Tools"
            GH["GitHub Tool"]:::tool
            ST["Stock Tool"]:::tool
            WK["Wikipedia Search"]:::tool
            click GH "https://github.com/venopyX/shellsense/blob/main/shellsense/tools/data/github.py"
            click ST "https://github.com/venopyX/shellsense/blob/main/shellsense/tools/data/stock.py"
            click WK "https://github.com/venopyX/shellsense/blob/main/shellsense/tools/data/wikipedia_search.py"
        end

        subgraph "Language Tools"
            TR["Translator"]:::tool
            click TR "https://github.com/venopyX/shellsense/blob/main/shellsense/tools/language/translator.py"
        end

        subgraph "Media Tools"
            SS["Screenshoter"]:::tool
            click SS "https://github.com/venopyX/shellsense/blob/main/shellsense/tools/media/screenshoter.py"
        end

        subgraph "Shell Tools"
            CE["Command Execution"]:::tool
            click CE "https://github.com/venopyX/shellsense/blob/main/shellsense/tools/shell/command_execution.py"
        end

        subgraph "Web Tools"
            CR["Crawler"]:::tool
            PH["ProductHunt"]:::tool
            WS["Web Search"]:::tool
            click CR "https://github.com/venopyX/shellsense/blob/main/shellsense/tools/web/crawler.py"
            click PH "https://github.com/venopyX/shellsense/blob/main/shellsense/tools/web/producthunt.py"
            click WS "https://github.com/venopyX/shellsense/blob/main/shellsense/tools/web/websearch.py"
        end
    end

    subgraph "AI Provider System"
        PF["Provider Factory"]:::core
        BP["Base Provider"]:::core
        OP["OpenAI Provider"]:::provider
        GP["Gemini Provider"]:::provider
        CP["Cloudflare Provider"]:::provider
        FR["Friendly AI Response"]:::core
        IP["Instructions Prompt"]:::core
        
        click BP "https://github.com/venopyX/shellsense/blob/main/shellsense/ai/providers/base_provider.py"
        click OP "https://github.com/venopyX/shellsense/blob/main/shellsense/ai/providers/openai_provider.py"
        click GP "https://github.com/venopyX/shellsense/blob/main/shellsense/ai/providers/gemini_provider.py"
        click CP "https://github.com/venopyX/shellsense/blob/main/shellsense/ai/providers/cloudflare_provider.py"
        click FR "https://github.com/venopyX/shellsense/blob/main/shellsense/ai/providers/friendly_ai_response.py"
        click IP "https://github.com/venopyX/shellsense/blob/main/shellsense/ai/prompts/instructions.py"
    end

    subgraph "Configuration & Utilities"
        SET["Settings"]:::utility
        ENV["Environment Config"]:::utility
        LOG["Logging Manager"]:::utility
        SC["System Context"]:::utility
        LD["Loading Utility"]:::utility
        
        click SET "https://github.com/venopyX/shellsense/blob/main/shellsense/config/settings.py"
        click ENV "https://github.com/venopyX/shellsense/blob/main/shellsense/config/example.env"
        click LOG "https://github.com/venopyX/shellsense/blob/main/shellsense/utils/logging_manager.py"
        click SC "https://github.com/venopyX/shellsense/blob/main/shellsense/utils/system_context.py"
        click LD "https://github.com/venopyX/shellsense/blob/main/shellsense/utils/loading.py"
    end

    subgraph "External Services"
        OAPI([OpenAI API]):::external
        GAPI([Gemini API]):::external
        CFAI([Cloudflare AI]):::external
        GIT([GitHub API]):::external
        SAPI([Stock API]):::external
        WAPI([Web Services]):::external
    end

    CLI --> TM
    TM --> BT
    BT --> CG & GH & ST & WK & TR & SS & CE & CR & PH & WS
    
    TM --> PF
    PF --> BP
    BP --> OP & GP & CP
    OP --> OAPI
    GP --> GAPI
    CP --> CFAI
    
    GH --> GIT
    ST --> SAPI
    CR & WS --> WAPI
    
    SET --> ENV
    TM --> SET
    PF --> SET
    
    classDef core fill:#a2d2ff,stroke:#333,stroke-width:2px
    classDef external fill:#95d5b2,stroke:#333,stroke-width:2px
    classDef decision fill:#ffd6a5,stroke:#333,stroke-width:2px
    classDef utility fill:#ffadad,stroke:#333,stroke-width:2px
    classDef tool fill:#bdb2ff,stroke:#333,stroke-width:2px
    classDef provider fill:#caffbf,stroke:#333,stroke-width:2px
```
