# encoredev/ai-chat architecture

> Architecture diagram of the GitHub repository encoredev/ai-chat, 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/encoredev/ai-chat
- Repository: https://github.com/encoredev/ai-chat

## Overview

##### Main Components
- Chat Service: Acts as the orchestrator that handles incoming messages from different platforms (Discord, Slack, Local).
- Provider Integrations:
– Chat Providers: Discord Service (under chat/provider/discord), Slack Service (under chat/provider/slack), and Local Chat Service (under chat/provider/local). Their directories include service files, database migration and query logic.
– LLM Providers: OpenAI and Gemini integrations are found in the llm/provider directory with corresponding client implementations.
- Bot Service: Handles the creation, storage, and management of bot profiles.
- LLM Service: Manages the crafting of prompts (including persona details), sending them to the LLM, processing streaming responses via pub/sub, and then communicating the results back to the Chat Service.
- Database Layers: Several services contain SQL migrations and query files (e.g., in bot/db, chat/service/db, chat/provider/discord/db) which represent persistent storage components.
- Infrastructure Services: Ancillary components include the pub/sub architecture for messaging between services as well as potential proxy handling (in the proxy directory) and commonly used utility functions (in pkg/fns).

##### Relationships and Interactions
- Data Flow from Users: Users interact with one of the chat interfaces (local web UI, Discord, or Slack). Their messages get received by the respective chat provider service.
- Messaging Pipeline: Each chat provider service publishes the message to the Chat Service (possibly using Encore’s pub/sub mechanism).
- Bot Interaction: Chat Service retrieves bot profiles and message histories from the Bot Service’s database layer and forwards the conversation context to the LLM Service.
- LLM Integration: The LLM Service uses provider-specific clients (OpenAI or Gemini) to send crafted prompts to the appropriate LLM, and responses are streamed back via pub/sub messaging.
- Response Handling: The LLM Service processes these responses and passes them back to the Chat Service, which then routes them to the correct chat platform.

##### Highlighted Architectural Patterns and Design Principles
- Microservices: The overall architecture is decomposed into service boundaries for each responsibility (chat orchestration, bot management, LLM prompt handling).
- Separation of Concerns: Each service handles a specific aspect – e.g., chat integrations are covered in a dedicated “chat” module while LLM integrations live within “llm”.
- Pub/Sub Communication: The design leverages pub/sub mechanisms to efficiently route messages between services.
- Environment-Agnostic Deployment: The use of Encore for streamlined local and cloud deployment, along with secrets management for API keys, demonstrates a design mindful of secure, scalable deployment.
- Provider Abstraction: The existence of separate provider directories indicates a flexible design that makes it easy to add or remove chat or LLM providers.

##### Including Relevant Technologies, Frameworks, or Libraries
- Encore (for rapid deployment and service orchestration)
- SQL scripts and migrations (for database initialization)
- Language-specific frameworks and libraries in Go (as seen from the go.mod file)
- NPM-based tooling, Tailwind, and Vite in the local chat front-end (for building the web UI)
- Pub/Sub messaging to integrate asynchronous communications across microservices

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Interfaces
    subgraph "External Interfaces"
        DUI("Discord Web UI"):::UI
        SUI("Slack Web UI"):::UI
        LUI("Local Web UI"):::UI
    end

    %% Chat Providers
    subgraph "Chat Providers"
        DCP("Discord Chat Provider"):::chatProvider
        SCP("Slack Chat Provider"):::chatProvider
        LCP("Local Chat Provider"):::chatProvider
        DPDB("Discord Provider DB"):::db
    end

    %% Core Services
    subgraph "Core Services"
        CS("Chat Service"):::coreService
        CSD("Chat Service DB"):::db
        BS("Bot Service"):::coreService
        BDB("Bot Service DB"):::db
        LS("LLM Service"):::coreService
    end

    %% LLM Providers
    subgraph "LLM Providers"
        OAI("OpenAI LLM Provider"):::llm
        GEM("Gemini LLM Provider"):::llm
    end

    %% Infrastructure
    subgraph "Infrastructure Services"
        PUBSUB("Pub/Sub Messaging"):::infra
        PROXY("Proxy Handler"):::infra
    end

    %% Common Utilities
    UTIL("Common Utilities"):::utils

    %% User to Chat Provider connections
    DUI -->|"sends message"| DCP
    SUI -->|"sends message"| SCP
    LUI -->|"sends message"| LCP

    %% Chat Providers to Chat Service
    DCP -->|"publish message"| CS
    SCP -->|"publish message"| CS
    LCP -->|"publish message"| CS

    %% Chat Service Relationships
    CS -->|"queries_bot"| BS
    CS -->|"sends_context"| LS
    CS ---|"uses_pubsub"| PUBSUB
    CS ---|"via_proxy"| PROXY
    CS --- CSD

    %% Bot Service Database
    BS --- BDB

    %% LLM Service interactions
    LS -->|"dispatch_prompt"| OAI
    LS -->|"dispatch_prompt"| GEM
    OAI -->|"stream_response"| LS
    GEM -->|"stream_response"| LS
    LS ---|"uses_pubsub"| PUBSUB

    %% Discord Provider DB connection
    DCP --- DPDB

    %% Legend (informational)
    subgraph "Legend"
        LEG1["<b>UI</b>: Chat Interfaces"]:::UI
        LEG2["<b>Chat Provider</b>: Platform-specific services"]:::chatProvider
        LEG3["<b>Core Service</b>: Orchestration components"]:::coreService
        LEG4["<b>LLM Provider</b>: LLM client implementations"]:::llm
        LEG5["<b>DB</b>: Database/Migration Layers"]:::db
        LEG6["<b>Infra</b>: Pub/Sub, Proxy, etc."]:::infra
        LEG7["<b>Utils</b>: Common Utility Functions"]:::utils
    end

    %% Click Events
    click CS "https://github.com/encoredev/ai-chat/tree/main/chat/service"
    click DCP "https://github.com/encoredev/ai-chat/tree/main/chat/provider/discord"
    click SCP "https://github.com/encoredev/ai-chat/tree/main/chat/provider/slack"
    click LCP "https://github.com/encoredev/ai-chat/tree/main/chat/provider/local"
    click CSD "https://github.com/encoredev/ai-chat/tree/main/chat/service/db"
    click DPDB "https://github.com/encoredev/ai-chat/tree/main/chat/provider/discord/db"
    click BS "https://github.com/encoredev/ai-chat/tree/main/bot"
    click BDB "https://github.com/encoredev/ai-chat/tree/main/bot/db"
    click LS "https://github.com/encoredev/ai-chat/tree/main/llm/service"
    click OAI "https://github.com/encoredev/ai-chat/tree/main/llm/provider/openai"
    click GEM "https://github.com/encoredev/ai-chat/tree/main/llm/provider/gemini"
    click PUBSUB "https://github.com/encoredev/ai-chat/blob/main/chat/service/pubsub.go"
    click PROXY "https://github.com/encoredev/ai-chat/blob/main/proxy/proxy.go"
    click UTIL "https://github.com/encoredev/ai-chat/tree/main/pkg/fns"

    %% Styles
    classDef UI fill:#FFECB3,stroke:#333,stroke-width:2px;
    classDef chatProvider fill:#BBDEFB,stroke:#333,stroke-width:2px;
    classDef coreService fill:#C8E6C9,stroke:#333,stroke-width:2px;
    classDef llm fill:#FFE0B2,stroke:#333,stroke-width:2px;
    classDef db fill:#D7CCC8,stroke:#333,stroke-width:2px;
    classDef infra fill:#E1BEE7,stroke:#333,stroke-width:2px;
    classDef utils fill:#F8BBD0,stroke:#333,stroke-width:2px;
```
