graph TD
    Client_TG[Telegram Client] --> Bot_TG[telegram_app.py]
    Client_DC[Discord Client] --> Bot_DC[discord_app.py]
    Client_UI[Gradio UI] --> Bot_UI[local_ui.py]

    Bot_TG --> Handler[core/message_handler.py]
    Bot_DC --> Handler
    Bot_UI --> Handler

    Handler --> State[State Manager<br>In-Memory Deque]
    Handler --> Cache[Cache Manager<br>SQLite]

    Handler --> RAG[RAG Engine]
    Handler --> Vision[Vision Engine]

    RAG --> Embed[sentence-transformers<br>all-MiniLM-L6-v2]
    RAG --> DB[(SQLite Vector DB)]
    RAG --> LLM[Ollama API<br>llama3]

    Vision --> VLM[Ollama API<br>llava]

sequenceDiagram
    autonumber
    actor User
    participant Platform as Discord/Telegram App
    participant Brain as Core Message Handler
    participant Cache as Cache Manager
    participant State as State Manager
    participant RAG as RAG Engine
    participant Vision as Vision Engine
    participant DB as SQLite DB
    participant Ollama as Local LLM (Ollama)

    User->>Platform: Sends /ask or Uploads Image

    alt Text Query (/ask)
        Platform->>Brain: handle_ask_command(user_id, query)
        Brain->>Cache: get(query_hash)

        alt Cache Hit
            Cache-->>Brain: Cached response
        else Cache Miss
            Cache-->>Brain: None
            Brain->>State: get_history(user_id)
            State-->>Brain: Last 3 interactions

            Brain->>RAG: retrieve(query)
            RAG->>DB: Vector similarity search
            DB-->>RAG: Top-K context chunks

            Brain->>RAG: generate_answer(query, context, history)
            RAG->>Ollama: POST /api/generate
            Ollama-->>RAG: Generated text
            RAG-->>Brain: Final answer

            Brain->>Cache: set(query_hash, answer)
        end

        Brain->>State: add_to_history(query + answer)
        Brain-->>Platform: Final response

    else Image Upload
        Platform->>Platform: Download image to temp folder
        Platform->>Brain: handle_image_upload(user_id, image_path)

        Brain->>State: add_to_history("[Uploaded Image]")
        Brain->>Vision: describe_image(image_path)

        Vision->>Ollama: POST /api/generate (llava)
        Ollama-->>Vision: Caption + tags
        Vision-->>Brain: Vision output

        Brain->>State: add_to_history(vision output)
        Brain-->>Platform: Final response

        Platform->>Platform: Delete temp file
    end

    Platform-->>User: Deliver final message