# ramakm/ai-chatbot architecture

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

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

## Overview

1. **Overall shape**
   - This is a small, monolithic Python chatbot service with two main faces: a browser UI and a server-side intent classifier.  
   - The repository is organized around a single runtime entrypoint, `app.py`, plus prebuilt model artifacts and a simple HTML/CSS frontend.

2. **User interaction flow**
   - A user opens the main page at `/`, which returns the chat interface from `templates/index.html`.
   - The page then sends chat messages to the backend over HTTP, described in the README as `POST /api/chat`.
   - The backend returns a bot reply plus a confidence score, and the frontend updates the conversation UI immediately.

3. **Frontend boundary**
   - Presentation lives in `templates/index.html` and the `static/` assets (`static/style.css`, `static/css.css`).
   - The UI is server-delivered HTML with client-side behavior layered on top, likely using the jQuery/Bootstrap stack mentioned in the README.
   - This frontend is responsible only for rendering, responsive layout, animations, and message display; it does not contain chatbot logic.

4. **Backend/API boundary**
   - `app.py` is the central orchestration layer: it serves the homepage, exposes the chat API, and provides a health endpoint at `/health`.
   - The README also indicates CORS support and structured error handling, so this layer acts as the clean boundary between browser requests and model inference.
   - The backend is the only place where user text is validated, classified, and turned into a response.

5. **Inference subsystem**
   - The runtime model bundle is stored in the repository root as `chatbot_model.h5`, `words.pkl`, and `classes.pkl`.
   - These files are the deployed inference assets: the neural network, the vocabulary/token index, and the intent label set.
   - At runtime, the backend uses these artifacts together to convert a user message into an intent prediction and select an answer.

6. **Intent and response data**
   - `intents.json` is the source-of-truth knowledge base for chatbot behavior.
   - It contains the intents, example phrases, and response options used both for training and for generating replies.
   - Changing chatbot behavior is primarily a data change here, not a code change.

7. **Training pipeline**
   - `train.py` is the offline model-building script.
   - Its job is to read `intents.json`, preprocess text, train the network, and regenerate the serialized artifacts (`chatbot_model.h5`, `words.pkl`, `classes.pkl`).
   - This is a separate lifecycle from serving: training happens out of band, while `app.py` consumes the saved outputs.

8. **Operational/runtime requirements**
   - `requirements.txt` defines the Python stack, which the README says includes FastAPI/Uvicorn plus TensorFlow/Keras and NLTK.
   - NLTK data (`punkt`, `wordnet`) is a prerequisite for text preprocessing.
   - `runtime.txt` pins the Python version for cloud deployment environments.

9. **Deployment and packaging**
   - The repo includes multiple deployment paths: `Dockerfile`, `docker-compose.yml`, `nginx.conf`, `Procfile`, `start.sh`, `start.bat`, and `runtime.txt`.
   - This indicates the app can run locally, in containers, or on PaaS-style platforms such as Heroku/Render/Railway.
   - `nginx.conf` suggests an optional reverse-proxy layer in front of the app when deployed in a production container setup.

10. **Cross-cutting concerns**
   - `README.md` highlights health checks, CORS, and environment-driven configuration (`WORKERS`, `LOG_LEVEL`, `CORS_ORIGINS`).
   - The `/health` endpoint exists for monitoring whether the service and model are loaded.
   - Because all model assets sit beside the app code in the repo root, the application is tightly coupled to those serialized files at startup.

11. **What to show in an architecture diagram**
   - Draw three major zones: browser UI, Python API service, and ML/model assets.
   - Show `templates/index.html` + `static/` serving the UI, `app.py` as the request handler, and `chatbot_model.h5`/`words.pkl`/`classes.pkl` as the inference bundle loaded by the backend.
   - Add `intents.json` and `train.py` as the offline training path that produces the runtime artifacts.
   - Optionally annotate the deployment edge with Docker/Nginx/Procfile as packaging, not business logic.

Main entry points: [`app.py`](https://github.com/ramakm/ai-chatbot/blob/main/app.py) (app.py), [`train.py`](https://github.com/ramakm/ai-chatbot/blob/main/train.py) (train.py), [`templates/index.html`](https://github.com/ramakm/ai-chatbot/blob/main/templates/index.html) (index.html), [`requirements.txt`](https://github.com/ramakm/ai-chatbot/blob/main/requirements.txt) (requirements)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Browser UI"]
  node_index_html["index.html<br/>template<br/>[index.html]"]
  node_style_css["style.css<br/>[style.css]"]
  node_css_css["css.css<br/>style<br/>[css.css]"]
end

subgraph group_service["API Service"]
  node_app["app.py<br/>web/api server<br/>[app.py]"]
  node_health(("Health<br/>endpoint<br/>[app.py]"))
  node_chat_api(("Chat API<br/>endpoint<br/>[app.py]"))
  node_home_page["Home page<br/>route<br/>[index.html]"]
end

subgraph group_ml["Inference Assets"]
  node_chatbot_model[("Model<br/>[chatbot_model.h5]")]
  node_words_pkl["Words<br/>vocab index<br/>[words.pkl]"]
  node_classes_pkl["Classes<br/>label set<br/>[classes.pkl]"]
end

subgraph group_training["Training Pipeline"]
  node_intents_json["Intents<br/>knowledge base<br/>[intents.json]"]
  node_train_py["train.py<br/>training script<br/>[train.py]"]
end

subgraph group_deploy["Deployment"]
  node_requirements["requirements<br/>python deps<br/>[requirements.txt]"]
  node_dockerfile["Dockerfile<br/>container build"]
  node_compose["compose<br/>local stack<br/>[docker-compose.yml]"]
  node_nginx_conf["nginx.conf<br/>proxy config<br/>[nginx.conf]"]
  node_procfile["Procfile<br/>process spec"]
  node_runtime_txt["runtime.txt<br/>python version<br/>[runtime.txt]"]
  node_start_sh["start.sh<br/>startup script<br/>[start.sh]"]
  node_start_bat["start.bat<br/>startup script<br/>[start.bat]"]
end

node_app -->|"serves"| node_home_page
node_app -->|"handles"| node_chat_api
node_app -->|"exposes"| node_health
node_home_page -->|"renders"| node_index_html
node_index_html -->|"uses"| node_style_css
node_index_html -->|"uses"| node_css_css
node_chat_api -->|"loads"| node_chatbot_model
node_chat_api -->|"vectorizes"| node_words_pkl
node_chat_api -->|"maps"| node_classes_pkl
node_chat_api -->|"responds with"| node_intents_json
node_train_py -->|"reads"| node_intents_json
node_train_py -->|"produces"| node_chatbot_model
node_train_py -->|"produces"| node_words_pkl
node_train_py -->|"produces"| node_classes_pkl
node_requirements -->|"supports"| node_app
node_requirements -->|"supports"| node_train_py
node_dockerfile -->|"packages"| node_app
node_compose -->|"orchestrates"| node_dockerfile
node_nginx_conf -->|"proxies"| node_app
node_procfile -->|"starts"| node_app
node_runtime_txt -->|"pins"| node_app
node_start_sh -->|"launches"| node_app
node_start_bat -->|"launches"| node_app

click node_app "https://github.com/ramakm/ai-chatbot/blob/main/app.py"
click node_health "https://github.com/ramakm/ai-chatbot/blob/main/app.py"
click node_chat_api "https://github.com/ramakm/ai-chatbot/blob/main/app.py"
click node_home_page "https://github.com/ramakm/ai-chatbot/blob/main/templates/index.html"
click node_index_html "https://github.com/ramakm/ai-chatbot/blob/main/templates/index.html"
click node_style_css "https://github.com/ramakm/ai-chatbot/blob/main/static/style.css"
click node_css_css "https://github.com/ramakm/ai-chatbot/blob/main/static/css.css"
click node_chatbot_model "https://github.com/ramakm/ai-chatbot/blob/main/chatbot_model.h5"
click node_words_pkl "https://github.com/ramakm/ai-chatbot/blob/main/words.pkl"
click node_classes_pkl "https://github.com/ramakm/ai-chatbot/blob/main/classes.pkl"
click node_intents_json "https://github.com/ramakm/ai-chatbot/blob/main/intents.json"
click node_train_py "https://github.com/ramakm/ai-chatbot/blob/main/train.py"
click node_requirements "https://github.com/ramakm/ai-chatbot/blob/main/requirements.txt"
click node_dockerfile "https://github.com/ramakm/ai-chatbot/tree/main/Dockerfile"
click node_compose "https://github.com/ramakm/ai-chatbot/blob/main/docker-compose.yml"
click node_nginx_conf "https://github.com/ramakm/ai-chatbot/blob/main/nginx.conf"
click node_procfile "https://github.com/ramakm/ai-chatbot/tree/main/Procfile"
click node_runtime_txt "https://github.com/ramakm/ai-chatbot/blob/main/runtime.txt"
click node_start_sh "https://github.com/ramakm/ai-chatbot/blob/main/start.sh"
click node_start_bat "https://github.com/ramakm/ai-chatbot/blob/main/start.bat"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_index_html,node_style_css,node_css_css toneBlue
class node_app,node_health,node_chat_api,node_home_page toneAmber
class node_chatbot_model,node_words_pkl,node_classes_pkl toneMint
class node_intents_json,node_train_py toneRose
class node_requirements,node_dockerfile,node_compose,node_nginx_conf,node_procfile,node_runtime_txt,node_start_sh,node_start_bat toneIndigo
```

## Components

### Browser UI

Server-rendered chat page and static presentation assets.

- [index.html](https://github.com/ramakm/ai-chatbot/blob/main/templates/index.html): template · Server-delivered chat interface markup. · `templates/index.html`
- [style.css](https://github.com/ramakm/ai-chatbot/blob/main/static/style.css): style · Primary UI styling for layout and presentation. · `static/style.css`
- [css.css](https://github.com/ramakm/ai-chatbot/blob/main/static/css.css): style · Additional stylesheet for the frontend. · `static/css.css`

### API Service

Main Python runtime that serves pages and handles chat requests.

- [app.py](https://github.com/ramakm/ai-chatbot/blob/main/app.py): web/api server · Main runtime entrypoint; serves the UI, chat API, and health endpoint. · `app.py`
- [Health](https://github.com/ramakm/ai-chatbot/blob/main/app.py): endpoint · Service readiness check exposed by the backend. · `app.py`
- [Chat API](https://github.com/ramakm/ai-chatbot/blob/main/app.py): endpoint · HTTP boundary for sending user messages and receiving replies. · `app.py`
- [Home page](https://github.com/ramakm/ai-chatbot/blob/main/templates/index.html): route · Serves the chat interface at the root path. · `templates/index.html`

### Inference Assets

Serialized model bundle used at runtime for intent prediction.

- [Model](https://github.com/ramakm/ai-chatbot/blob/main/chatbot_model.h5): keras model · Serialized neural network used for intent inference. · `chatbot_model.h5`
- [Words](https://github.com/ramakm/ai-chatbot/blob/main/words.pkl): vocab index · Token vocabulary used to vectorize user input. · `words.pkl`
- [Classes](https://github.com/ramakm/ai-chatbot/blob/main/classes.pkl): label set · Intent label list used to map predictions to responses. · `classes.pkl`

### Training Pipeline

Offline script and source data used to rebuild the model bundle.

- [Intents](https://github.com/ramakm/ai-chatbot/blob/main/intents.json): knowledge base · Source data of intents, example phrases, and responses. · `intents.json`
- [train.py](https://github.com/ramakm/ai-chatbot/blob/main/train.py): training script · Offline pipeline that preprocesses intents and rebuilds the model artifacts. · `train.py`

### Deployment

Container and process files for local, container, and PaaS-style runs.

- [requirements](https://github.com/ramakm/ai-chatbot/blob/main/requirements.txt): python deps · Runtime dependency specification for the service and training stack. · `requirements.txt`
- [Dockerfile](https://github.com/ramakm/ai-chatbot/tree/main/Dockerfile): container build · Build definition for running the chatbot in a container. · `Dockerfile`
- [compose](https://github.com/ramakm/ai-chatbot/blob/main/docker-compose.yml): local stack · Container orchestration for local multi-service execution. · `docker-compose.yml`
- [nginx.conf](https://github.com/ramakm/ai-chatbot/blob/main/nginx.conf): proxy config · Optional reverse-proxy configuration for production container setups. · `nginx.conf`
- [Procfile](https://github.com/ramakm/ai-chatbot/tree/main/Procfile): process spec · Process entry definition for PaaS-style deployment. · `Procfile`
- [runtime.txt](https://github.com/ramakm/ai-chatbot/blob/main/runtime.txt): python version · Pinned Python runtime version for deployment platforms. · `runtime.txt`
- [start.sh](https://github.com/ramakm/ai-chatbot/blob/main/start.sh): startup script · Unix startup helper for running the service. · `start.sh`
- [start.bat](https://github.com/ramakm/ai-chatbot/blob/main/start.bat): startup script · Windows startup helper for running the service. · `start.bat`

## Connections

- app.py → Home page: serves · The backend returns the chat page for the root route.
- app.py → Chat API: handles · The backend receives chat messages and returns predictions.
- app.py → Health: exposes · The backend provides a readiness/health endpoint.
- Home page → index.html: renders · The root route serves the HTML chat interface.
- index.html → style.css: uses · The page is styled by the main stylesheet.
- index.html → css.css: uses · The page also includes additional styling assets.
- Chat API → Model: loads · The API uses the trained model to infer intents.
- Chat API → Words: vectorizes · User text is converted using the saved vocabulary.
- Chat API → Classes: maps · Predictions are mapped to intent labels.
- Chat API → Intents: responds with · Intent data supplies the bot responses.
- train.py → Intents: reads · Training starts from the intent knowledge base.
- train.py → Model: produces · Training regenerates the serialized network artifact.
- train.py → Words: produces · Training saves the vocabulary artifact.
- train.py → Classes: produces · Training saves the label-set artifact.
- requirements → app.py: supports · Declared dependencies support the runtime service.
- requirements → train.py: supports · Declared dependencies also support offline training.
- Dockerfile → app.py: packages · The container image wraps the Python service.
- compose → Dockerfile: orchestrates · Compose coordinates containerized startup.
- nginx.conf → app.py: proxies · Nginx can sit in front of the backend in production.
- Procfile → app.py: starts · PaaS process definitions launch the service.
- runtime.txt → app.py: pins · Deployment runtime version constrains the service environment.
- start.sh → app.py: launches · Unix startup script starts the application.
- start.bat → app.py: launches · Windows startup script starts the application.