How alfredfrancis/ai-chatbot-framework works
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”)