# flowline-io/flowbot architecture

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

- Interactive diagram: https://gitdiagram.com/flowline-io/flowbot
- Repository: https://github.com/flowline-io/flowbot

## Overview

##### Project Type and Purpose
- This project is a chatbot framework designed to serve as a platform for message publish/subscribe, handling message cron jobs, triggers, tasks, pipelines, and workflow actions.
- The file structure, with its clear separation of code into directories such as cmd, internal, pkg, and deployments, indicates an architecture comprised of distinct modules (agents, bots, platforms, workflows, data store).

##### File Structure for Key Architectural Patterns
- Top-level directories like cmd (running entry-point binaries for agent and composer), internal (which organizes the agents, bots, workflow, platforms, server, and store components), and pkg (supplying common libraries such as event handling, execution engines, and provider adapters) point to a modular, layered architecture.
- The “internal/platforms” directory specifically houses integrations for Slack, Discord, and Tailchat – which fulfills the instruction to emphasize a dedicated platforms layer placed before the agent modules.
- A large “internal/bots” directory suggests that specialized bot behaviors (e.g. for finance, dev, GitHub, etc.) encapsulate core message-handling logic, while agent modules in “cmd/agent” and “internal/agents” represent the overall chatbot engine.
- Several configuration, migration, and deployment files indicate support for managing state and scalability.

##### README for Additional Insights on System Design
- The README highlights that flowbot operates as both a chat bot and a message pipeline/hub.
- The caption “Architecture” along with an image (architecture.png) implies a layered design where components interact through well-defined interfaces.
- Dependencies such as Go 1.21 and various CI/CD workflows further confirm a modern, production-grade system.

a. Main Components:
- External Communication Platforms: Represent external systems (e.g., Slack, Discord, Tailchat) which the chatbot will communicate with.
- Platforms Integration Layer: This layer (found in internal/platforms) is responsible for receiving and sending messages from/to external platforms. Emphasize that this layer is placed in front of (or “before”) the agent system.
- Agent Module: Covers both the entry-point in cmd/agent and related internal/agents functionalities, handling the core chatbot logic and coordination.
- Message Publishing/Subscription Hub: Abstracted across packages (e.g., pkg/event, pkg/executer) and internal/server components that route messages, trigger events, and manage pipelines.
- Workflow and Task Orchestration: Managed by modules in internal/workflow and supported by cmd/composer, handling workflows, scheduling tasks, and orchestrating multi-step processes.
- Data Store Layer: Provided by internal/store (and its MySQL adapter), which persists chat events, user data, workflow state, etc.
- Utility and Provider Adapters: Modules in pkg/providers and pkg/utils supply common services such as file handling, external provider integrations, and command execution (in pkg/executer).

b. Relationships and Interactions:
- From the Platforms layer, show connections feeding into the “Agent Module” which processes messages.
- Both the agent and bots interact with the “Message Hub” to publish/subscribe to events and trigger workflows.
- The “Workflow Engine & Composer” receives tasks from the Bot layer and orchestrates multi-step processes.
- Persistent state is maintained through the “Data Store Layer,” which is accessed by various components.

c. Architectural Patterns:
- Use layering to separate external integrations, business logic (agents and bots), workflow orchestration, and persistent data management.
- Clearly demarcate the responsibilities: platforms handling I/O with external services, agents acting as core processing units, and bots extending functionality through specialized actions.
- The design principles of modularity and separation of concerns should be highlighted to ensure clarity and ease of maintenance.

d. Specify Relevant Technologies:
- Language: Go (version 1.21 or newer).
- CI/CD: GitHub Actions workflows for building, releasing, and Docker deployments.
- Data persistence: Likely backed by a SQL database using the MySQL adapter found in internal/store/mysql.
- Third-party libraries/frameworks: Various packages within pkg (such as pkg/event, pkg/executer, and pkg/cache) and integrations in pkg/providers.

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% External Communication Platforms
    subgraph "External Communication Platforms"
        slack["Slack"]:::external
        discord["Discord"]:::external
        tailchat["Tailchat"]:::external
    end

    %% Platforms Integration Layer
    subgraph "Platforms Integration Layer"
        platforms["Platforms Integration"]:::platform
    end

    %% Agent Module
    subgraph "Agent Module"
        agent_entry["Agent Entry (cmd/agent)"]:::agent
        agent_core["Agent Core (internal/agents)"]:::agent
    end

    %% Bots Engine
    subgraph "Bots Engine"
        bots["Bots Engine"]:::bots
    end

    %% Message Publishing/Subscription Hub
    subgraph "Message Hub"
        event_bus["Event Bus"]:::hub
        executer["Executer"]:::hub
    end

    %% Workflow and Task Orchestration
    subgraph "Workflow Engine & Composer"
        workflow_engine["Workflow Engine"]:::workflow
        composer["Composer (cmd/composer)"]:::workflow
    end

    %% Data Store Layer
    subgraph "Data Store Layer"
        store_core["Store (internal/store)"]:::data
        mysql_adapter["MySQL Adapter (internal/store/mysql)"]:::data
    end

    %% Utility and Provider Adapters
    subgraph "Utility & Provider Adapters"
        providers["Providers"]:::utils
        utils["Utils"]:::utils
    end

    %% Connections - Message Flow
    
    %% External Platforms to Platforms Integration Layer
    slack -->|"sendsMsg"| platforms
    discord -->|"sendsMsg"| platforms
    tailchat -->|"sendsMsg"| platforms

    %% Platforms Integration Layer to Agent Module
    platforms -->|"routesMsg"| agent_entry
    agent_entry -->|"passesControl"| agent_core

    %% Agent Module to Bots Engine
    agent_core -->|"invokes"| bots

    %% Interactions with Message Hub
    agent_core -->|"publishes"| event_bus
    agent_core -->|"executes"| executer
    bots -->|"publishes"| event_bus
    bots -->|"executes"| executer

    %% Bots Engine to Workflow Engine & Composer
    bots -->|"triggers"| composer
    event_bus -->|"notifies"| workflow_engine
    workflow_engine -->|"coordinates"| composer

    %% Persistent storage from various components
    agent_core -->|"storesData"| store_core
    bots -->|"storesData"| store_core
    workflow_engine -->|"storesData"| store_core
    composer -->|"storesData"| store_core

    %% Utility and Provider support arrows (dotted)
    providers -.->|"supports"| agent_core
    providers -.->|"supports"| bots
    providers -.->|"supports"| workflow_engine
    utils -.->|"supports"| agent_core
    utils -.->|"supports"| bots
    utils -.->|"supports"| workflow_engine

    %% Click Events
    click slack "https://github.com/flowline-io/flowbot/tree/master/internal/platforms/slack"
    click discord "https://github.com/flowline-io/flowbot/tree/master/internal/platforms/discord"
    click tailchat "https://github.com/flowline-io/flowbot/tree/master/internal/platforms/tailchat"
    click platforms "https://github.com/flowline-io/flowbot/tree/master/internal/platforms"
    click agent_entry "https://github.com/flowline-io/flowbot/tree/master/cmd/agent"
    click agent_core "https://github.com/flowline-io/flowbot/tree/master/internal/agents"
    click bots "https://github.com/flowline-io/flowbot/tree/master/internal/bots"
    click event_bus "https://github.com/flowline-io/flowbot/tree/master/pkg/event"
    click executer "https://github.com/flowline-io/flowbot/tree/master/pkg/executer"
    click workflow_engine "https://github.com/flowline-io/flowbot/tree/master/internal/workflow"
    click composer "https://github.com/flowline-io/flowbot/tree/master/cmd/composer"
    click store_core "https://github.com/flowline-io/flowbot/tree/master/internal/store"
    click mysql_adapter "https://github.com/flowline-io/flowbot/tree/master/internal/store/mysql"
    click providers "https://github.com/flowline-io/flowbot/tree/master/pkg/providers"
    click utils "https://github.com/flowline-io/flowbot/tree/master/pkg/utils"

    %% Styles
    classDef external fill:#ffcccc,stroke:#cc0000,stroke-width:2px;
    classDef platform fill:#ccffcc,stroke:#009900,stroke-width:2px;
    classDef agent fill:#ccccff,stroke:#0000ff,stroke-width:2px;
    classDef bots fill:#e6ccff,stroke:#6600cc,stroke-width:2px;
    classDef hub fill:#fff2cc,stroke:#ff9900,stroke-width:2px;
    classDef workflow fill:#ccffff,stroke:#00cccc,stroke-width:2px;
    classDef data fill:#f2ccff,stroke:#9900cc,stroke-width:2px;
    classDef utils fill:#d9ead3,stroke:#38761d,stroke-width:2px;
```
