# swordonfire/superbot architecture

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

- Interactive diagram: https://gitdiagram.com/swordonfire/superbot
- Repository: https://github.com/swordonfire/superbot

## Overview

##### Main Components

a) External Services Layer:
- Telegram API Integration
- Twitter API Integration
- User Interfaces (Telegram Bot & Admin UI)

b) API Layer (FastAPI):
- Member Routes
- LLM Routes
- Admin Routes
- Telegram Routes
- Twitter Routes

c) Core Services:
- Telegram Service
- Twitter Service
- Member Service

d) AI/LLM Infrastructure:
- Local LLM Engine (Llama.cpp)
- RAG Pipeline
- Chunker
- Embedder (GIST-small-Embedding)
- Retriever
- Vector Store (ChromaDB)

##### Knowledge Base Query Flow
**User → Telegram Bot → API Gateway → LLM Service → RAG Pipeline → Vector Store**

##### Member Discovery Flow
**User → Telegram Bot → API Gateway → Member Service → LLM Service → Member Database**

##### Content Generation Flow
**Admin → API Gateway → Twitter Service → LLM Service → Human Approval → Twitter API**

##### Important Elements

- Security layer showing local LLM deployment
- RAG pipeline detailed view
- Clear separation between local and external services
- Data flow between components
- Caching mechanisms (if any)
- Authentication/Authorization flows

##### Technical Details to Note

- FastAPI as the main web framework
- ChromaDB as the vector store
- Llama.cpp for LLM inference
- GIST-small-Embedding for embeddings
- Python-telegram-bot integration
- Environment configuration flow

##### Additional Recommendations

- Version information for major components
- Scaling points for future enhancements
- Planned integrations (Langchain, Weaviate)
- Components that handle privacy-sensitive data
- Monitoring and logging points

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph UI[User Interfaces]
        F["Frontend UI"]
    end

    F --> API

    subgraph Backend[API & Core Services]
        API["API Gateway (FastAPI)"]
        TGS["Telegram Service"]
        TWS["Twitter Service"]
        MS["Member Service"]
        LLM["Local LLM Integration"]
        RAG["RAG Pipeline (Chunker, Retriever, Embedder)"]
        DB["Vector Database (ChromaDB)"]
    end

    API --> TGS
    API --> TWS
    API --> MS
    API --> LLM

    TGS -- "inference & response" --> LLM
    TWS -- "inference request" --> LLM

    LLM --> RAG
    RAG --> DB
    MS --> DB

    CONFIG["Configuration & Security"]
    SCRIPTS["Auxiliary Scripts & Utilities"]

    CONFIG -.-> API
    CONFIG -.-> TGS
    CONFIG -.-> TWS
    CONFIG -.-> MS
    CONFIG -.-> LLM
    CONFIG -.-> RAG

    SCRIPTS -.-> LLM
    SCRIPTS -.-> DB

    subgraph LEGEND[Legend]
        leg1["Frontend UI - frontend/"]
        leg2["API Gateway (FastAPI) - src/api/"]
        leg3["Local LLM Integration - src/llm/"]
        leg4["RAG Pipeline - src/rag/"]
        leg5["Telegram Service - src/services/telegram_service.py"]
        leg6["Twitter Service - src/services/twitter_service.py"]
        leg7["Member Service - src/services/member_service.py"]
        leg8["Vector Database (ChromaDB) - src/db/"]
        leg9["Configuration & Security - src/core/"]
        leg10["Auxiliary Scripts & Utilities - scripts/"]
    end

    class F frontend
    class API backend
    class TGS service
    class TWS service
    class MS service
    class LLM llm
    class RAG rag
    class DB database
    class CONFIG config
    class SCRIPTS scripts

    class leg1 frontend
    class leg2 backend
    class leg3 llm
    class leg4 rag
    class leg5 service
    class leg6 service
    class leg7 service
    class leg8 database
    class leg9 config
    class leg10 scripts

    click F "https://github.com/swordonfire/SuperBot/tree/main/frontend/"
    click API "https://github.com/swordonfire/SuperBot/tree/main/src/api/"
    click LLM "https://github.com/swordonfire/SuperBot/tree/main/src/llm/"
    click RAG "https://github.com/swordonfire/SuperBot/tree/main/src/rag/"
    click TGS "https://github.com/swordonfire/SuperBot/blob/main/src/services/telegram_service.py"
    click TWS "https://github.com/swordonfire/SuperBot/blob/main/src/services/twitter_service.py"
    click MS "https://github.com/swordonfire/SuperBot/blob/main/src/services/member_service.py"
    click DB "https://github.com/swordonfire/SuperBot/tree/main/src/db/"
    click CONFIG "https://github.com/swordonfire/SuperBot/tree/main/src/core/"
    click SCRIPTS "https://github.com/swordonfire/SuperBot/tree/main/scripts/"

    classDef frontend fill:#AED6F1,stroke:#2E86C1,stroke-width:2px;
    classDef backend fill:#F9E79F,stroke:#D4AC0D,stroke-width:2px;
    classDef service fill:#A9DFBF,stroke:#27AE60,stroke-width:2px;
    classDef llm fill:#FAD7A0,stroke:#E67E22,stroke-width:2px;
    classDef rag fill:#F5CBA7,stroke:#E74C3C,stroke-width:2px;
    classDef database fill:#D5F5E3,stroke:#2ECC71,stroke-width:2px;
    classDef config fill:#D2B4DE,stroke:#8E44AD,stroke-width:2px;
    classDef scripts fill:#E8DAEF,stroke:#AF7AC5,stroke-width:2px;
    classDef legend fill:#EBF5FB,stroke:#5499C7,stroke-width:1px,stroke-dasharray: 5,5;
```
