# willkuerlich/botlike architecture

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

- Interactive diagram: https://gitdiagram.com/willkuerlich/botlike
- Repository: https://github.com/willkuerlich/botlike

## Overview

##### Main Components

a) Network Clients Layer
- Three parallel client modules: WhatsApp, Telegram, and Discord
- Client connection handler
- Message queue system
- Event bindings
- Action handlers (text/image)

b) Core Bot Layer
- Botlike core system
- State management (using XState based on the PromptMachine files)
- Universal message handler
- Command processing system

c) Service Layer
- OpenAI API integration
- Image Server (Automatic1111) integration
- EdenAI integration
- Supabase integration
- Logger service

d) Command Layer
- Command parser
- Command validators
- Action handlers
- I18n support

**[External Services]**
- ↕
**[Network Clients Layer]**
- ↕
**[Core Bot Layer]**
- ↕
**[Command & Service Layer]**
- ↕
**[Database & Storage]**

##### Key Relationships to Highlight

a) Message Flow:
- How messages flow from network clients through the universal message handler
- How commands are parsed and routed to appropriate services
- Message queue system for each platform

b) State Management:
- How the PromptMachine manages bot state
- Interaction between state and message handling

c) Service Integration:
- Connections to external services (OpenAI, Image Server)
- Database interactions with Supabase

##### Technical Details

- TypeScript integration
- Environment configuration
- Build process
- Development mode vs Production mode

##### Specific Implementation Notes

- Error handling paths
- Rate limiting and queue management

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph External
        OpenAI[OpenAI API]
        ImageServer[Automatic1111 Server]
        EdenAI[EdenAI Service]
        SupabaseDB[(Supabase DB)]
    end

    subgraph NetworkClients
        direction TB
        WA[WhatsApp Client]:::client
        TG[Telegram Client]:::client
        DC[Discord Client]:::client
        
        WAQ[Message Queue]:::queue
        TGQ[Message Queue]:::queue
        DCQ[Message Queue]:::queue
        
        WA --> WAQ
        TG --> TGQ
        DC --> DCQ
    end

    subgraph CoreBot
        UMH[Universal Message Handler]:::core
        State[State Management]:::core
        BotCore[Bot Core System]:::core
        
        UMH --> State
        State --> BotCore
    end

    subgraph Services
        OAI[OpenAI Integration]:::service
        ImgSrv[Image Server Integration]:::service
        Eden[EdenAI Integration]:::service
        SupaInt[Supabase Integration]:::service
        Logger[Logger Service]:::service
    end

    subgraph CommandLayer
        CmdParser[Command Parser]:::command
        CmdValid[Command Validator]:::command
        ActHandler[Action Handlers]:::command
        I18N[I18n Support]:::command
        
        CmdParser --> CmdValid
        CmdValid --> ActHandler
        ActHandler --> I18N
    end

    %% Network Flow
    WAQ --> UMH
    TGQ --> UMH
    DCQ --> UMH

    %% Core Flow
    UMH --> CmdParser
    BotCore --> Services

    %% Service Connections
    OAI --> OpenAI
    ImgSrv --> ImageServer
    Eden --> EdenAI
    SupaInt --> SupabaseDB

    %% Logging
    ActHandler --> Logger

    %% Click Events
    click WA "https://github.com/willkuerlich/botlike/tree/master/networkClient/whatsapp"
    click TG "https://github.com/willkuerlich/botlike/tree/master/networkClient/telegram"
    click DC "https://github.com/willkuerlich/botlike/tree/master/networkClient/discord"
    click WAQ "https://github.com/willkuerlich/botlike/blob/master/networkClient/whatsapp/messageQueue.ts"
    click TGQ "https://github.com/willkuerlich/botlike/blob/master/networkClient/telegram/messageQueue.ts"
    click DCQ "https://github.com/willkuerlich/botlike/blob/master/networkClient/discord/messageQueue.ts"
    click UMH "https://github.com/willkuerlich/botlike/blob/master/src/botlike/prompt/universalMessageHandler.ts"
    click State "https://github.com/willkuerlich/botlike/blob/master/src/botlike/bot/default/state/PromptMachine.ts"
    click BotCore "https://github.com/willkuerlich/botlike/tree/master/src/botlike/core"
    click OAI "https://github.com/willkuerlich/botlike/tree/master/src/api/oai"
    click ImgSrv "https://github.com/willkuerlich/botlike/tree/master/src/api/imageServer"
    click Eden "https://github.com/willkuerlich/botlike/tree/master/src/api/edenAI"
    click SupaInt "https://github.com/willkuerlich/botlike/blob/master/modules/supabase/supabaseClient.ts"
    click Logger "https://github.com/willkuerlich/botlike/blob/master/src/services/logger/commandLogger.ts"
    click CmdParser "https://github.com/willkuerlich/botlike/blob/master/src/commander/generalCommandsParser.ts"
    click CmdValid "https://github.com/willkuerlich/botlike/blob/master/src/commander/validateActionRequest.ts"
    click ActHandler "https://github.com/willkuerlich/botlike/tree/master/src/actions"
    click I18N "https://github.com/willkuerlich/botlike/tree/master/src/lib/i18n"

    %% Styling
    classDef client fill:#3498db,stroke:#2980b9,color:white
    classDef core fill:#2ecc71,stroke:#27ae60,color:white
    classDef service fill:#f1c40f,stroke:#f39c12,color:black
    classDef command fill:#9b59b6,stroke:#8e44ad,color:white
    classDef queue fill:#95a5a6,stroke:#7f8c8d,color:white

    %% Legend
    subgraph Legend
        L1[Client Component]:::client
        L2[Core Component]:::core
        L3[Service Component]:::service
        L4[Command Component]:::command
        L5[Queue Component]:::queue
    end
```
