# mhtbtanvir/plugbot architecture

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

- Interactive diagram: https://gitdiagram.com/mhtbtanvir/plugbot
- Repository: https://github.com/mhtbtanvir/plugbot

## Overview

##### Project type and purpose
- This is a full-stack, plugin-style chatbot system consisting of:
- A Python/Flask-based backend (app.py) exposing a REST API for chat interactions.
- An intent-classification model (PyTorch) with training scripts (train.py) and utilities (nltk_utils.py).
- A fallback conversational layer using Hugging Face’s DialoGPT-medium.
- Two frontends: a built-in “static” Flask templates/UI and a standalone-frontend directory with its own HTML/CSS/JS.
- Purpose: Provide an embeddable chatbot engine that first attempts intent matching, then falls back to a generative model.

##### File structure
- Top-level files:
- app.py – Flask server entrypoint, loads model/data, defines chat endpoints.
- chat.py – CLI for interactive chat on the command line.
- train.py – Script to train/update the intent classifier.
- model.py & nltk_utils.py – Model definition and NLP utilities.
- intents.json & data.pth – Core data: intent definitions and trained weights.
- Directories:
- static & templates – Flask’s default folder structure for built-in frontend assets and Jinja HTML templates.
- standalone-frontend – A self-contained frontend (vanilla JS / HTML / CSS) that can call the same API endpoints externally.

##### README for additional insights
- Confirms Flask + PyTorch + NLTK stack.
- Two modes: training (train.py) and serving (app.py).
- Fallback logic: use HF DialoGPT if intent confidence is low.
- Designed to be easily “plugged” into any frontend framework.

a. Main components:
- Frontend Layer
– “Built-in” Flask UI (templates & static/)
– Standalone frontend (HTML/CSS/JS)
- Backend Layer (Flask API)
– HTTP server (app.py)
– Intent classifier sub-module (model.py + nltk_utils.py + data.pth + intents.json)
– Fallback service adapter (DialoGPT Medium via Hugging Face API)
- Persistence Layer
– intents.json (configuration store)
– data.pth (model weights)
- Training Pipeline
– train.py reading intents.json, producing data.pth
- External Service
– Hugging Face DialoGPT-medium API

b. Relationships and data flow:
1. User interacts with a frontend → sends HTTP request to Flask API (/chat endpoint).
2. Flask API loads/uses the intent classifier:
- If confidence ≥ threshold → returns intent-based response.
- Otherwise → routes query to DialoGPT via external HTTP call, returns generative response.
3. train.py reads intents.json → pre-processes with nltk_utils → trains a PyTorch model → writes data.pth.
4. On server startup, app.py loads data.pth & intents.json into memory.

c. Architectural patterns/design principles:
- Layered architecture: UI → API → Model → External Service.
- Separation of concerns: training pipeline separated from serving pipeline.
- Fallback chain of responsibility: intent handler first, then generative adapter.

d. Key technologies/frameworks:
- Flask (web server/API)
- PyTorch (model training & inference)
- NLTK (tokenization, bag-of-words)
- Hugging Face API (DialoGPT-medium)
- Vanilla JS / HTML / CSS (frontend)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Frontend Layer"
        BuiltinStatic["Built-in Static Assets"]:::frontend
        BuiltinTemplates["Built-in Templates/UI"]:::frontend
        StandaloneAppJS["Standalone Frontend app.js"]:::frontend
        StandaloneHTML["Standalone Frontend base.html"]:::frontend
        StandaloneCSS["Standalone Frontend style.css"]:::frontend
        StandaloneImages["Standalone Frontend images/"]:::frontend
    end

    subgraph "Client Interfaces"
        ChatCLI["CLI Interactive Chat"]:::frontend
    end

    subgraph "Backend Layer"
        FlaskAPI["Flask Chat API"]:::backend
        IntentClassifier["Intent Classifier Module"]:::backend
        NLPUtils["NLP Utilities"]:::backend
        FallbackAdapter["Fallback Conversational Adapter"]:::backend
    end

    subgraph "Persistence Layer"
        IntentsJSON["intents.json"]:::data
        ModelWeights["data.pth"]:::data
    end

    subgraph "Training Pipeline"
        TrainScript["Training Script (train.py)"]:::train
        ModelDef["Model Definition (model.py)"]:::train
        NLTKTrainUtils["NLP Utilities (nltk_utils.py)"]:::train
    end

    ExternalService["Hugging Face DialoGPT-medium API"]:::external

    %% Frontend to API
    BuiltinStatic -->|HTTP/REST| FlaskAPI
    BuiltinTemplates -->|HTTP/REST| FlaskAPI
    StandaloneAppJS -->|HTTP/REST| FlaskAPI
    StandaloneHTML -->|HTTP/REST| FlaskAPI
    StandaloneCSS -->|HTTP/REST| FlaskAPI
    StandaloneImages -->|HTTP/REST| FlaskAPI

    %% CLI to Backend
    ChatCLI -->|invoke| IntentClassifier
    ChatCLI -->|fallback| FallbackAdapter

    %% API routing
    FlaskAPI -->|route to| IntentClassifier
    FlaskAPI -->|fallback| FallbackAdapter

    %% Intent classifier dependencies
    IntentClassifier -->|loads| IntentsJSON
    IntentClassifier -->|loads| ModelWeights
    IntentClassifier -->|uses| NLPUtils

    %% Fallback adapter external call
    FallbackAdapter -->|HTTP| ExternalService

    %% API startup loads data
    FlaskAPI -->|loads| IntentsJSON
    FlaskAPI -->|loads| ModelWeights

    %% Training pipeline flow
    TrainScript -->|reads| IntentsJSON
    TrainScript -->|uses| NLTKTrainUtils
    TrainScript -->|uses| ModelDef
    TrainScript -->|writes| ModelWeights

    %% Click Events
    click FlaskAPI "https://github.com/mhtbtanvir/plugbot/blob/master/app.py"
    click ChatCLI "https://github.com/mhtbtanvir/plugbot/blob/master/chat.py"
    click TrainScript "https://github.com/mhtbtanvir/plugbot/blob/master/train.py"
    click ModelDef "https://github.com/mhtbtanvir/plugbot/blob/master/model.py"
    click NLTKUtils "https://github.com/mhtbtanvir/plugbot/blob/master/nltk_utils.py"
    click IntentsJSON "https://github.com/mhtbtanvir/plugbot/blob/master/intents.json"
    click ModelWeights "https://github.com/mhtbtanvir/plugbot/blob/master/data.pth"
    click BuiltinStatic "https://github.com/mhtbtanvir/plugbot/tree/master/static/"
    click BuiltinTemplates "https://github.com/mhtbtanvir/plugbot/tree/master/templates/"
    click StandaloneAppJS "https://github.com/mhtbtanvir/plugbot/blob/master/standalone-frontend/app.js"
    click StandaloneHTML "https://github.com/mhtbtanvir/plugbot/blob/master/standalone-frontend/base.html"
    click StandaloneCSS "https://github.com/mhtbtanvir/plugbot/blob/master/standalone-frontend/style.css"
    click StandaloneImages "https://github.com/mhtbtanvir/plugbot/tree/master/standalone-frontend/images/"

    %% Styles
    classDef frontend fill:#E8F1F2,stroke:#333,stroke-width:1px
    classDef backend fill:#FDEBD0,stroke:#333,stroke-width:1px
    classDef data fill:#D5F5E3,stroke:#333,stroke-width:1px
    classDef train fill:#FADBD8,stroke:#333,stroke-width:1px
    classDef external fill:#E8DAEF,stroke:#333,stroke-width:1px
```
