# alfredfrancis/ai-chatbot-framework architecture

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

- Interactive diagram: https://gitdiagram.com/alfredfrancis/ai-chatbot-framework
- Repository: https://github.com/alfredfrancis/ai-chatbot-framework

## Overview

##### Project Type & Purpose
- This is a full-stack, self-hosted AI chatbot framework.
- Backend: Python + FastAPI APIs for both Admin Dashboard and Bot Runtime.
- Frontend: React/Next.js low-code admin UI and embeddable chat widget.
- Bot Core: NLU + Dialogue Manager + Memory + Integrations.
- Persistence: MongoDB via Motor.
- Channel Integrations: REST, Facebook Messenger, external LLM (OpenAI/Ollama).
- Deployed via Docker Compose or Kubernetes/Helm.

##### Main Components to Model
A. Frontend (Next.js)
- Admin UI pages under frontend/app/admin   (manages bots, intents, entities, training, settings)
- Public chat widget under frontend/app/page.tsx + static widget script
B. Backend API (FastAPI)
- Admin endpoints (app/admin/* routes)
- Bot runtime endpoints (app/bot/channels/rest & facebook routes)
- Shared modules (app/config.py, app/database.py, app/dependencies.py, app/main.py)
C. Bot Engine
- NLU pipeline (entity_extractors, featurizers, intent_classifiers, LLM zero-shot module)
- Dialogue Manager (session handling, turn-taking logic)
- Memory module (stores context & chat logs in MongoDB)
D. Database
- MongoDB (persistent storage for bots, intents, entities, chatlogs, memory)
E. External Services
- Facebook Messenger API
- OpenAI or local LLM (via Ollama)
F. DevOps/Deployment
- Docker Compose files (docker-compose.yml, docker-compose.dev.yml, docker-compose.llm.yml)
- Dockerfiles (backend, frontend, nginx script)
- Kubernetes Helm chart under helm/ai-chatbot-framework (defines Deployments, Services, Ingress)

##### Relationships & Data Flows
- Frontend Admin UI ⟷ Backend Admin APIs (HTTP JSON calls)
- Chat Widget (browser) → Backend /bot REST endpoint → Bot Engine
- Bot Engine calls NLU pipeline → Dialogue Manager → Memory (MongoDB)
- Bot Engine may call external LLM service → update context → produce response
- Backend persists chat logs & bot definitions in MongoDB → Admin UI reads from DB
- Backend exposes Webhook for Facebook → Facebook Messenger ↔ /bot/channels/facebook routes

##### Architectural Patterns & Principles
- Layered/Clean Architecture: Presentation (FastAPI routers, Next.js UI) → Application (Bot Engine modules) → Infrastructure (MongoDB, external APIs)
- Modular separation: “app/admin” vs. “app/bot” sub-packages
- Plugin-style NLU pipeline: interchangeable featurizers, classifiers, extractors, LLM modules
- Infrastructure as Code: Docker + Helm for reproducible deployment

##### Essential Elements
- Labels: name each component clearly (e.g., “Intent Classifier”, “Chatlogs Store”)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend" 
        direction TB
        AdminUI["Admin UI<br/>(Next.js + React)"]:::frontend
        ChatWidget["Chat Widget<br/>(Static Script)"]:::frontend
    end

    %% Backend API Layer
    subgraph "Backend API Server"
        direction TB
        Shared["Shared Modules<br/>(FastAPI + Pydantic)"]:::backend
        subgraph "Admin API"
            direction TB
            AdminAPI["Admin Endpoints"]:::backend
        end
        subgraph "Bot Runtime API"
            direction TB
            BotAPI["Bot Runtime Endpoints"]:::backend
        end
    end

    %% Bot Engine Layer
    subgraph "Bot Engine" 
        direction TB
        subgraph "NLU Pipeline" 
            direction TB
            EntityExtractors["Entity Extractors"]:::engine
            Featurizers["Featurizers"]:::engine
            IntentClassifiers["Intent Classifiers"]:::engine
            LLMModule["LLM Zero-Shot Module"]:::engine
        end
        DialogueMgr["Dialogue Manager"]:::engine
        MemoryMod["Memory Module"]:::engine
    end

    %% Database Layer
    MongoDB["MongoDB<br/>(Motor driver)"]:::database

    %% External Services
    subgraph "External Services"
        direction TB
        Facebook["Facebook Messenger API"]:::external
        LLMService["OpenAI/Ollama LLM"]:::external
    end

    %% DevOps / Deployment
    subgraph "Deployment Infrastructure"
        direction TB
        DockerCompose["Docker Compose Stacks"]:::infra
        Dockerfiles["Dockerfiles"]:::infra
        HelmChart["Kubernetes / Helm Chart"]:::infra
    end

    %% Connections
    AdminUI -->|"HTTP/JSON"| AdminAPI
    AdminAPI -->|"CRUD"| MongoDB
    ChatWidget -->|"HTTP REST"| BotAPI
    BotAPI -->|"calls"| EntityExtractors
    BotAPI -->|"calls"| Featurizers
    BotAPI -->|"calls"| IntentClassifiers
    BotAPI -->|"calls"| LLMModule
    EntityExtractors --> DialogueMgr
    Featurizers --> DialogueMgr
    IntentClassifiers --> DialogueMgr
    LLMModule --> DialogueMgr
    DialogueMgr --> MemoryMod
    MemoryMod --> MongoDB
    BotAPI -->|"Webhook"| Facebook
    BotAPI -->|"HTTP"| LLMService
    AdminAPI --> MongoDB

    %% Click Events
    click AdminUI "https://github.com/alfredfrancis/ai-chatbot-framework/tree/master/frontend/app/admin"
    click ChatWidget "https://github.com/alfredfrancis/ai-chatbot-framework/blob/master/app/static/widget/script.js"
    click ChatWidget "https://github.com/alfredfrancis/ai-chatbot-framework/blob/master/frontend/app/page.tsx"
    click AdminAPI "https://github.com/alfredfrancis/ai-chatbot-framework/blob/master/app/admin/bots/routes.py"
    click AdminAPI "https://github.com/alfredfrancis/ai-chatbot-framework/blob/master/app/admin/intents/routes.py"
    click AdminAPI "https://github.com/alfredfrancis/ai-chatbot-framework/blob/master/app/admin/entities/routes.py"
    click AdminAPI "https://github.com/alfredfrancis/ai-chatbot-framework/blob/master/app/admin/chatlogs/routes.py"
    click AdminAPI "https://github.com/alfredfrancis/ai-chatbot-framework/blob/master/app/admin/integrations/routes.py"
    click AdminAPI "https://github.com/alfredfrancis/ai-chatbot-framework/blob/master/app/admin/train/routes.py"
    click BotAPI "https://github.com/alfredfrancis/ai-chatbot-framework/blob/master/app/bot/channels/rest/routes.py"
    click BotAPI "https://github.com/alfredfrancis/ai-chatbot-framework/blob/master/app/bot/channels/facebook/routes.py"
    click Shared "https://github.com/alfredfrancis/ai-chatbot-framework/blob/master/app/config.py"
    click Shared "https://github.com/alfredfrancis/ai-chatbot-framework/blob/master/app/database.py"
    click Shared "https://github.com/alfredfrancis/ai-chatbot-framework/blob/master/app/dependencies.py"
    click Shared "https://github.com/alfredfrancis/ai-chatbot-framework/blob/master/app/main.py"
    click EntityExtractors "https://github.com/alfredfrancis/ai-chatbot-framework/tree/master/app/bot/nlu/entity_extractors/"
    click Featurizers "https://github.com/alfredfrancis/ai-chatbot-framework/tree/master/app/bot/nlu/featurizers/"
    click IntentClassifiers "https://github.com/alfredfrancis/ai-chatbot-framework/tree/master/app/bot/nlu/intent_classifiers/"
    click LLMModule "https://github.com/alfredfrancis/ai-chatbot-framework/blob/master/app/bot/nlu/llm/zero_shot_nlu_openai.py"
    click LLMModule "https://github.com/alfredfrancis/ai-chatbot-framework/blob/master/scripts/ollama/entrypoint.sh"
    click DialogueMgr "https://github.com/alfredfrancis/ai-chatbot-framework/blob/master/app/bot/dialogue_manager/dialogue_manager.py"
    click DialogueMgr "https://github.com/alfredfrancis/ai-chatbot-framework/blob/master/app/bot/dialogue_manager/models.py"
    click DialogueMgr "https://github.com/alfredfrancis/ai-chatbot-framework/blob/master/app/bot/dialogue_manager/utils.py"
    click MemoryMod "https://github.com/alfredfrancis/ai-chatbot-framework/blob/master/app/bot/memory/memory_saver_mongo.py"
    click MemoryMod "https://github.com/alfredfrancis/ai-chatbot-framework/blob/master/app/bot/memory/models.py"
    click MongoDB "https://github.com/alfredfrancis/ai-chatbot-framework/blob/master/app/admin/bots/store.py"
    click MongoDB "https://github.com/alfredfrancis/ai-chatbot-framework/blob/master/app/admin/intents/store.py"
    click MongoDB "https://github.com/alfredfrancis/ai-chatbot-framework/blob/master/app/admin/entities/store.py"
    click MongoDB "https://github.com/alfredfrancis/ai-chatbot-framework/blob/master/app/admin/chatlogs/store.py"
    click MongoDB "https://github.com/alfredfrancis/ai-chatbot-framework/blob/master/app/admin/integrations/store.py"
    click MongoDB "https://github.com/alfredfrancis/ai-chatbot-framework/blob/master/app/admin/train/store.py"
    click DockerCompose "https://github.com/alfredfrancis/ai-chatbot-framework/blob/master/docker-compose.yml"
    click DockerCompose "https://github.com/alfredfrancis/ai-chatbot-framework/blob/master/docker-compose.dev.yml"
    click DockerCompose "https://github.com/alfredfrancis/ai-chatbot-framework/blob/master/docker-compose.llm.yml"
    click Dockerfiles "https://github.com/alfredfrancis/ai-chatbot-framework/tree/master/Dockerfile"
    click Dockerfiles "https://github.com/alfredfrancis/ai-chatbot-framework/tree/master/frontend/Dockerfile"
    click Dockerfiles "https://github.com/alfredfrancis/ai-chatbot-framework/blob/master/scripts/nginx/default.conf"
    click HelmChart "https://github.com/alfredfrancis/ai-chatbot-framework/tree/master/helm/ai-chatbot-framework/"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366D6,color:#0366D6,stroke-width:1px;
    classDef backend fill:#E6FFFA,stroke:#00A081,color:#00664C,stroke-width:1px;
    classDef engine fill:#FFF4E6,stroke:#D97706,color:#B45309,stroke-width:1px;
    classDef database fill:#FFF7E6,stroke:#D97706,color:#92400E,stroke-width:1px;
    classDef external fill:#F0F0F0,stroke:#6B7280,color:#374151,stroke-width:1px;
    classDef infra fill:#F3E8FF,stroke:#7C3AED,color:#4C1D95,stroke-width:1px;
```
