# qaaph-zyld/chatbots architecture

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

- Interactive diagram: https://gitdiagram.com/qaaph-zyld/chatbots
- Repository: https://github.com/qaaph-zyld/chatbots

## Overview

##### Project type and purpose
- This is a full-stack, modular “Customizable Chatbots Platform.”
- It provides a React-based web UI, an embeddable web widget, and a rich Node.js/Express backend with chat-engine and NLP modules, persistent storage, analytics, and multi-channel integrations.

##### File structure
- Top-level “src/” contains:
- api/ (Express controllers, routes, Swagger docs)
- client/ (React SPA under src/client)
- bot/ & nlp/ (chatbot core: engine implementations, NLP processors)
- services/ (business-logic layer)
- database/ (Mongoose connection + schemas)
- integrations/ (Slack, web, channel abstractions)
- auth/ & enterprise/security/ (authentication, RBAC, audit logging)
- analytics/ & monitoring/ (data-collection, Prometheus exporter)
- context/, workflow, templates, training (conversation flow & training pipelines)
- web-widget/ (standalone embeddable widget with its own build)
- Deployment artifacts: Dockerfile, docker-compose(.yml), kubernetes/ (Helm chart), GitHub workflows.
- Static/demo sites under public/, demos/, community/forum/, website/.
- Scripts/ orchestrates CI/CD, testing, security audits, backups.

##### README for additional insights
- Core features: multiple AI engines (Botpress, Hugging Face), conversation templates, NLP, multi-channel.
- Advanced: context management, knowledge-base, analytics dashboard, training UI, RBAC.
- Tech stack: Node.js ≥16, Express, React, MongoDB, Docker, Kubernetes, Prometheus, Jest, Playwright.
- Architecture principles: modular design, factory patterns, DI, environment-driven config.

## Diagram (Mermaid)

```mermaid
graph TB
  %% Frontend Layer
  subgraph "Frontend" 
    ReactSPA["React SPA"]:::frontend
    WebWidget["Embeddable Web Widget"]:::frontend
    subgraph "Static & Demo Sites"
      CommunityForum["Community Forum"]:::frontend
      VoiceDemo["Voice Interface Demo"]:::frontend
      PublicStatic["Public Static Build"]:::frontend
      MarketingSite["Marketing Website"]:::frontend
    end
  end

  %% API Gateway & Web Server
  subgraph "API Gateway & Web Server"
    ExpressApp["Express App Entry (app.js)"]:::api
    ExpressServer["Express Server Entry (server.js)"]:::api
    Controllers["Controllers"]:::api
    RoutesFile["Routes File"]:::api
    RoutesDir["Routes Directory"]:::api
    SwaggerDocs["Swagger Docs (docs)"]:::api
    SwaggerDir["Swagger Directory"]:::api
    Middleware["Middleware"]:::api
  end

  %% Chatbot Core & Business Logic
  subgraph "Chatbot Core & Services"
    BotFactory["Bot Engine Factory"]:::core
    BotEngines["Bot Engine Implementations"]:::core
    NLP["NLP Modules"]:::core
    NLPProc["NLP Processors"]:::core
    ConvService["Conversation & Template Services"]:::core
    Templates["Bot Templates"]:::core
  end

  %% Data & Persistence
  subgraph "Data & Persistence"
    DBConn1["DB Connection"]:::data
    DBConn2["DB Connection Config"]:::data
    Schemas["Mongoose Schemas"]:::data
    ClientStorage["Client-Side Storage"]:::data
    MongoDB["MongoDB"]:::data
  end

  %% Integrations & External Channels
  subgraph "Integrations & External"
    IntegrationMgr["Integration Manager"]:::external
    IntegrationService["Integration Service"]:::external
    WebChannel["Web Channel"]:::external
    SlackService["Slack Service"]:::external
    ExternalAI["External AI Engines"]:::external
    KBAPIs["Knowledge Base / External APIs"]:::external
  end

  %% Analytics & Monitoring
  subgraph "Analytics & Monitoring"
    AnalyticsSvc["Analytics Services"]:::analytics
    Prometheus["Prometheus Exporter"]:::analytics
    MetricsServer["Metrics Server"]:::analytics
    MonUtils["Monitoring Utilities"]:::analytics
  end

  %% Enterprise Security & RBAC
  subgraph "Security & RBAC"
    AuthService["Auth Service"]:::security
    AuthMiddleware["Auth Middleware"]:::security
    EnterpriseSecurity["Audit & RBAC"]:::security
  end

  %% Deployment & DevOps
  subgraph "Deployment & DevOps"
    DockerfileNode["Dockerfile"]:::devops
    Compose["docker-compose.yml"]:::devops
    ComposeProd["docker-compose.production.yml"]:::devops
    ComposeStaging["docker-compose.staging.yml"]:::devops
    K8s["Kubernetes Charts"]:::devops
    Helm["Helm Chart"]:::devops
    CICD["CI/CD Workflows"]:::devops
  end

  %% Connections
  ReactSPA -->|"API Requests"| ExpressApp
  WebWidget -->|"API Requests"| ExpressApp
  CommunityForum -->|"Static Traffic"| WebWidget
  VoiceDemo -->|"Static Traffic"| WebWidget
  PublicStatic -->|"Static Traffic"| ReactSPA
  MarketingSite -->|"Static Traffic"| ReactSPA

  ExpressApp --> Middleware
  ExpressApp --> Controllers
  ExpressServer --> Controllers
  Controllers -->|uses| RoutesFile
  Controllers -->|uses| RoutesDir
  Controllers -->|documents| SwaggerDocs
  Controllers -->|documents| SwaggerDir
  Middleware -->|auth/logging| AuthMiddleware

  Controllers -->|calls| ConvService
  ConvService -->|uses| BotFactory
  BotFactory -->|creates| BotEngines
  ConvService -->|uses| NLP
  NLP -->|processes| NLPProc
  ConvService -->|manages| Templates

  ConvService -->|reads/writes| MongoDB
  MongoDB --> DBConn1
  MongoDB --> DBConn2
  DBConn1 --> Schemas
  Schemas --> ClientStorage

  ConvService -->|events| AnalyticsSvc
  AnalyticsSvc --> Prometheus
  AnalyticsSvc --> MetricsServer
  AnalyticsSvc --> MonUtils

  ConvService -->|integrates| IntegrationMgr
  IntegrationMgr --> IntegrationService
  IntegrationService --> WebChannel
  IntegrationService --> SlackService
  IntegrationService --> ExternalAI
  IntegrationService --> KBAPIs

  ExpressApp -->|secures| AuthService
  AuthService --> AuthMiddleware
  AuthService --> EnterpriseSecurity

  CICD --> DockerfileNode
  CICD --> Compose
  CICD --> ComposeProd
  CICD --> ComposeStaging
  CICD --> K8s
  K8s --> Helm

  %% Click Events
  click ReactSPA "https://github.com/qaaph-zyld/chatbots/tree/master/src/client/"
  click WebWidget "https://github.com/qaaph-zyld/chatbots/tree/master/src/web-widget/"
  click CommunityForum "https://github.com/qaaph-zyld/chatbots/tree/master/community/forum/"
  click VoiceDemo "https://github.com/qaaph-zyld/chatbots/tree/master/demos/voice-interface/"
  click PublicStatic "https://github.com/qaaph-zyld/chatbots/tree/master/public/"
  click MarketingSite "https://github.com/qaaph-zyld/chatbots/tree/master/website/"
  click ExpressApp "https://github.com/qaaph-zyld/chatbots/blob/master/src/app.js"
  click ExpressServer "https://github.com/qaaph-zyld/chatbots/blob/master/src/server.js"
  click Controllers "https://github.com/qaaph-zyld/chatbots/tree/master/src/api/controllers/"
  click RoutesFile "https://github.com/qaaph-zyld/chatbots/blob/master/src/api/routes.js"
  click RoutesDir "https://github.com/qaaph-zyld/chatbots/tree/master/src/api/routes/"
  click SwaggerDocs "https://github.com/qaaph-zyld/chatbots/tree/master/src/api/docs/"
  click SwaggerDir "https://github.com/qaaph-zyld/chatbots/tree/master/src/api/swagger/"
  click Middleware "https://github.com/qaaph-zyld/chatbots/tree/master/src/middleware/"
  click BotFactory "https://github.com/qaaph-zyld/chatbots/blob/master/src/bot/engines/engine.factory.js"
  click BotEngines "https://github.com/qaaph-zyld/chatbots/tree/master/src/bot/engines/"
  click NLP "https://github.com/qaaph-zyld/chatbots/tree/master/src/bot/nlp/"
  click NLPProc "https://github.com/qaaph-zyld/chatbots/tree/master/src/bot/nlp/processors/"
  click ConvService "https://github.com/qaaph-zyld/chatbots/tree/master/src/services/"
  click Templates "https://github.com/qaaph-zyld/chatbots/tree/master/src/bot/templates/"
  click DBConn1 "https://github.com/qaaph-zyld/chatbots/blob/master/src/database/connection.js"
  click DBConn2 "https://github.com/qaaph-zyld/chatbots/blob/master/src/database/db.connection.js"
  click Schemas "https://github.com/qaaph-zyld/chatbots/tree/master/src/database/schemas/"
  click ClientStorage "https://github.com/qaaph-zyld/chatbots/tree/master/src/storage/"
  click IntegrationMgr "https://github.com/qaaph-zyld/chatbots/blob/master/src/integrations/integration.manager.js"
  click IntegrationService "https://github.com/qaaph-zyld/chatbots/blob/master/src/integrations/integration.service.js"
  click WebChannel "https://github.com/qaaph-zyld/chatbots/blob/master/src/integrations/channels/web.channel.js"
  click SlackService "https://github.com/qaaph-zyld/chatbots/blob/master/src/integrations/slack.service.js"
  click AnalyticsSvc "https://github.com/qaaph-zyld/chatbots/tree/master/src/analytics/"
  click Prometheus "https://github.com/qaaph-zyld/chatbots/blob/master/src/monitoring/prometheus-exporter.service.js"
  click MetricsServer "https://github.com/qaaph-zyld/chatbots/blob/master/src/monitoring/metrics-server.js"
  click MonUtils "https://github.com/qaaph-zyld/chatbots/tree/master/src/monitoring/"
  click AuthService "https://github.com/qaaph-zyld/chatbots/blob/master/src/auth/auth.service.js"
  click AuthMiddleware "https://github.com/qaaph-zyld/chatbots/blob/master/src/auth/auth.middleware.js"
  click EnterpriseSecurity "https://github.com/qaaph-zyld/chatbots/tree/master/src/enterprise/security/"
  click DockerfileNode "https://github.com/qaaph-zyld/chatbots/tree/master/Dockerfile"
  click Compose "https://github.com/qaaph-zyld/chatbots/blob/master/docker-compose.yml"
  click ComposeProd "https://github.com/qaaph-zyld/chatbots/blob/master/docker-compose.production.yml"
  click ComposeStaging "https://github.com/qaaph-zyld/chatbots/blob/master/docker-compose.staging.yml"
  click K8s "https://github.com/qaaph-zyld/chatbots/tree/master/kubernetes/"
  click Helm "https://github.com/qaaph-zyld/chatbots/tree/master/kubernetes/helm-chart/"
  click CICD "https://github.com/qaaph-zyld/chatbots/tree/master/.github/workflows/"

  %% Styles
  classDef frontend fill:#D6E9FF,stroke:#2196F3,stroke-width:1px
  classDef api fill:#E8F5E9,stroke:#4CAF50,stroke-width:1px
  classDef core fill:#FFF3E0,stroke:#FF9800,stroke-width:1px
  classDef data fill:#F3E5F5,stroke:#9C27B0,stroke-width:1px
  classDef external fill:#FFEBEE,stroke:#F44336,stroke-width:1px
  classDef analytics fill:#E0F7FA,stroke:#00ACC1,stroke-width:1px
  classDef security fill:#ECEFF1,stroke:#607D8B,stroke-width:1px
  classDef devops fill:#FFFDE7,stroke:#FBC02D,stroke-width:1px
```
