# hexastack/hexabot architecture

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

- Interactive diagram: https://gitdiagram.com/hexastack/hexabot
- Repository: https://github.com/hexastack/hexabot

## Overview

##### Project type and purpose
- Full-stack, micro-modular AI chatbot/agent platform (“Hexabot v2”).
- Frontend admin panel (Next.js), backend REST/WebSocket API (NestJS + MongoDB), embeddable chat widget (React), plus Docker Compose orchestration and extension/plugin system.

##### File structure
- Top-level modules:
– /api: NestJS monolith subdivided into feature modules (chat, analytics, user, cms, nlp, migration, websocket, etc.).
– /frontend: Next.js admin UI with pages, components, contexts, hooks, and i18n assets.
– /widget: standalone React live chat widget.
– /docker: Docker Compose definitions for all services.
- Configuration files: Dockerfiles, .env examples, tslint/eslint, Nest CLI config.
- The API folder uses MVC (controllers, services, repositories, schemas) plus interceptors, guards, interceptors, plugin/extension subsystem.

##### README for additional insights
- Core features: LLM & NLU integration, multi-channel/widget, visual flow editor, plugin system, multi-lingual, analytics, real-time inbox/handover.
- Docker-driven local/dev/prod orchestration.
- CLI to scaffold and run services (ollama, redis, smtp, widget, nginx).

##### Detailed but not over-segmented
– At the top: Browser clients (Admin UI, Embedded Widget)
– Middle tier: Nginx → Docker network routing to Admin container & Widget container → API container
– Bottom tier: MongoDB, Redis, LLM Engine

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    subgraph "Browser Clients"
        direction TB
        AdminUI["Admin UI (Next.js)"]:::frontend
        Widget["Chat Widget (React)"]:::frontend
    end

    %% Orchestration Layer
    subgraph "Orchestration & Proxy"
        direction TB
        Nginx["Nginx Reverse Proxy"]:::orchestration
        CLI["CLI (hexabot-cli)"]:::orchestration
        subgraph "Docker Compose"
            direction TB
            FrontendC["Admin Container"]:::frontend
            WidgetC["Widget Container"]:::frontend
            APIc["API Server Container"]:::backend
        end
    end

    %% API Internals
    subgraph "API Internals (NestJS Monolith)" 
        direction TB
        FM["Feature Modules (chat, analytics, user, cms, nlp, migration, websocket, etc.)"]:::backend
        RedisAdapter["WebSocket Gateway & Redis Adapter"]:::backend
        PluginLoader["Extensions/Plugin Subsystem"]:::backend
    end

    %% Datastores & External
    subgraph "Data & External Services"
        direction TB
        Mongo["MongoDB"]:::datastore
        Redis["Redis"]:::datastore
        LLM["LLM/NLU Engine"]:::external
    end

    %% Connections: Clients to Proxy
    AdminUI -->|"HTTP REST / GraphQL"| Nginx
    AdminUI -->|"WebSocket (Live Inbox)"| Nginx
    Widget -->|"REST (Config)"| Nginx
    Widget -->|"WebSocket (Chat)"| Nginx

    %% Proxy to Containers
    Nginx --> FrontendC
    Nginx --> WidgetC
    Nginx --> APIc

    %% Containers to Internals
    APIc --> FM
    APIc --> RedisAdapter
    APIc --> PluginLoader

    %% Internals to Data/External
    FM -->|"REST Data"| Mongo
    FM -->|"pub/sub"| Redis
    FM -->|"RPC to LLM"| LLM
    RedisAdapter -->|"pub/sub"| Redis

    %% Orchestration CLI
    CLI -->|"orchestrates"| DockerCompose["Docker Compose"]:::orchestration

    %% Click Events
    click AdminUI "https://github.com/hexastack/hexabot/tree/main/frontend/"
    click Widget "https://github.com/hexastack/hexabot/tree/main/widget/"
    click APIc "https://github.com/hexastack/hexabot/tree/main/api/"
    click Mongo "https://github.com/hexastack/hexabot/blob/main/docker/docker-compose.yml"
    click Redis "https://github.com/hexastack/hexabot/blob/main/docker/docker-compose.redis.yml"
    click LLM "https://github.com/hexastack/hexabot/blob/main/docker/docker-compose.ollama.yml"
    click RedisAdapter "https://github.com/hexastack/hexabot/tree/main/api/src/websocket/"
    click RedisAdapter "https://github.com/hexastack/hexabot/blob/main/api/src/websocket/adapters/redis-io.adapter.ts"
    click PluginLoader "https://github.com/hexastack/hexabot/tree/main/api/src/plugins/"
    click PluginLoader "https://github.com/hexastack/hexabot/tree/main/api/src/extensions/channels/"
    click PluginLoader "https://github.com/hexastack/hexabot/tree/main/api/src/extensions/helpers/"
    click PluginLoader "https://github.com/hexastack/hexabot/tree/main/api/src/extensions/helpers/llm-nlu/"
    click CLI "https://github.com/hexastack/hexabot/blob/main/api/src/cli.ts"
    click Nginx "https://github.com/hexastack/hexabot/blob/main/docker/nginx/secure/default.conf.template"
    click Nginx "https://github.com/hexastack/hexabot/blob/main/docker/nginx/unsecure/default.conf.template"
    click APIc "https://github.com/hexastack/hexabot/tree/main/api/Dockerfile"
    click APIc "https://github.com/hexastack/hexabot/blob/main/api/Dockerfile.base"
    click FrontendC "https://github.com/hexastack/hexabot/tree/main/frontend/Dockerfile"
    click WidgetC "https://github.com/hexastack/hexabot/tree/main/widget/Dockerfile"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0277BD,color:#000
    classDef backend fill:#C8E6C9,stroke:#2E7D32,color:#000
    classDef datastore fill:#FFF3E0,stroke:#FB8C00,color:#000
    classDef external fill:#ECEFF1,stroke:#455A64,color:#000
    classDef orchestration fill:#FFE0B2,stroke:#EF6C00,color:#000
```
