# rahid-khan/fag-chatbot architecture

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

- Interactive diagram: https://gitdiagram.com/rahid-khan/fag-chatbot
- Repository: https://github.com/rahid-khan/fag-chatbot

## Overview

FAQ Chatbot accepts questions through a Flask web interface, semantically matches them against normalized FAQ data, and returns either a confidence-qualified answer or a fallback with suggestions. The main path runs from browser interaction through the HTTP route, response service, retrieval, and dataset; request and chat events are logged separately. The README also documents local chat persistence and a standalone evaluation workflow. The sampled source confirms the request, retrieval, loading, and logging links; unsampled UI wiring and evaluation details are represented only where documented or supported by the tree.

Main entry points: [`app/chatbot.py`](https://github.com/rahid-khan/fag-chatbot/blob/main/app/chatbot.py) (Response policy), [`static/js/chat.js`](https://github.com/rahid-khan/fag-chatbot/blob/main/static/js/chat.js) (Chat interaction), [`app/routes.py`](https://github.com/rahid-khan/fag-chatbot/blob/main/app/routes.py) (HTTP routes), [`app/retrieval.py`](https://github.com/rahid-khan/fag-chatbot/blob/main/app/retrieval.py) (Semantic retrieval)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Web interface"]
  node_browser["Chat interface<br/>[index.html]"]
  node_chat_js["Chat interaction<br/>[chat.js]"]
  node_local_storage[("Browser storage")]
end

subgraph group_service["Chat service"]
  node_app_factory["Flask app<br/>[__init__.py]"]
  node_routes["HTTP routes<br/>[routes.py]"]
  node_api["JSON responses<br/>[api.py]"]
  node_chatbot["Response policy<br/>[chatbot.py]"]
  node_config["Runtime settings<br/>[config.py]"]
end

subgraph group_retrieval["FAQ retrieval"]
  node_loader["FAQ loader<br/>[file_loader.py]"]
  node_faq_data[("FAQ dataset<br/>[faq.json]")]
  node_retriever["Semantic retrieval<br/>[retrieval.py]"]
  node_preprocess["Text preprocessing<br/>[preprocessing.py]"]
  node_model["Sentence Transformer"]
end

subgraph group_operations["Logging and evaluation"]
  node_logger["Structured logger<br/>[logger.py]"]
  node_log_file[("Chat logs")]
  node_evaluation["Evaluation runner"]
  node_eval_data["Evaluation cases<br/>[eval_set.json]"]
end

node_user(("Chat user"))

node_user -->|"asks"| node_chat_js
node_chat_js -->|"posts question"| node_routes
node_routes -->|"requests answer"| node_chatbot
node_chatbot -->|"loads FAQ"| node_loader
node_loader -->|"reads"| node_faq_data
node_chatbot -->|"retrieves match"| node_retriever
node_retriever -->|"normalizes text"| node_preprocess
node_retriever -->|"encodes and scores"| node_model
node_retriever -->|"uses loaded rows"| node_faq_data
node_chatbot -->|"reads settings"| node_config
node_routes -->|"formats response"| node_api
node_routes -->|"logs request"| node_logger
node_chatbot -->|"logs query"| node_logger
node_logger -->|"writes events"| node_log_file
node_app_factory -->|"registers routes"| node_routes
node_app_factory -->|"reads settings"| node_config
node_app_factory -->|"configures logging"| node_logger
node_browser -->|"loads script"| node_chat_js
node_chat_js -->|"persists chat"| node_local_storage
node_chat_js -->|"updates interface"| node_browser
node_evaluation -->|"reads cases"| node_eval_data
node_evaluation -->|"evaluates responses"| node_chatbot

click node_browser "https://github.com/rahid-khan/fag-chatbot/blob/main/templates/index.html"
click node_chat_js "https://github.com/rahid-khan/fag-chatbot/blob/main/static/js/chat.js"
click node_app_factory "https://github.com/rahid-khan/fag-chatbot/blob/main/app/__init__.py"
click node_routes "https://github.com/rahid-khan/fag-chatbot/blob/main/app/routes.py"
click node_api "https://github.com/rahid-khan/fag-chatbot/blob/main/app/api.py"
click node_chatbot "https://github.com/rahid-khan/fag-chatbot/blob/main/app/chatbot.py"
click node_config "https://github.com/rahid-khan/fag-chatbot/blob/main/app/config.py"
click node_loader "https://github.com/rahid-khan/fag-chatbot/blob/main/utils/file_loader.py"
click node_faq_data "https://github.com/rahid-khan/fag-chatbot/blob/main/data/faq.json"
click node_retriever "https://github.com/rahid-khan/fag-chatbot/blob/main/app/retrieval.py"
click node_preprocess "https://github.com/rahid-khan/fag-chatbot/blob/main/app/preprocessing.py"
click node_logger "https://github.com/rahid-khan/fag-chatbot/blob/main/utils/logger.py"
click node_evaluation "https://github.com/rahid-khan/fag-chatbot/blob/main/scripts/evaluate_chatbot.py"
click node_eval_data "https://github.com/rahid-khan/fag-chatbot/blob/main/data/eval_set.json"

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_browser,node_chat_js,node_local_storage,node_user toneBlue
class node_app_factory,node_routes,node_api,node_chatbot,node_config toneAmber
class node_loader,node_faq_data,node_retriever,node_preprocess,node_model toneMint
class node_logger,node_log_file,node_evaluation,node_eval_data toneRose
```

## Components

### Web interface

- [Chat interface](https://github.com/rahid-khan/fag-chatbot/blob/main/templates/index.html): `templates/index.html`
- [Chat interaction](https://github.com/rahid-khan/fag-chatbot/blob/main/static/js/chat.js): `static/js/chat.js`
- **Browser storage**

### Chat service

- [Flask app](https://github.com/rahid-khan/fag-chatbot/blob/main/app/__init__.py): `app/__init__.py`
- [HTTP routes](https://github.com/rahid-khan/fag-chatbot/blob/main/app/routes.py): `app/routes.py`
- [JSON responses](https://github.com/rahid-khan/fag-chatbot/blob/main/app/api.py): `app/api.py`
- [Response policy](https://github.com/rahid-khan/fag-chatbot/blob/main/app/chatbot.py): `app/chatbot.py`
- [Runtime settings](https://github.com/rahid-khan/fag-chatbot/blob/main/app/config.py): `app/config.py`

### FAQ retrieval

- [FAQ loader](https://github.com/rahid-khan/fag-chatbot/blob/main/utils/file_loader.py): `utils/file_loader.py`
- [FAQ dataset](https://github.com/rahid-khan/fag-chatbot/blob/main/data/faq.json): `data/faq.json`
- [Semantic retrieval](https://github.com/rahid-khan/fag-chatbot/blob/main/app/retrieval.py): `app/retrieval.py`
- [Text preprocessing](https://github.com/rahid-khan/fag-chatbot/blob/main/app/preprocessing.py): `app/preprocessing.py`
- **Sentence Transformer**

### Logging and evaluation

- [Structured logger](https://github.com/rahid-khan/fag-chatbot/blob/main/utils/logger.py): `utils/logger.py`
- **Chat logs**
- [Evaluation runner](https://github.com/rahid-khan/fag-chatbot/blob/main/scripts/evaluate_chatbot.py): `scripts/evaluate_chatbot.py`
- [Evaluation cases](https://github.com/rahid-khan/fag-chatbot/blob/main/data/eval_set.json): `data/eval_set.json`

### Other components

- **Chat user**

## Connections

- Chat user → Chat interaction: asks
- Chat interaction → HTTP routes: posts question
- HTTP routes → Response policy: requests answer
- Response policy → FAQ loader: loads FAQ
- FAQ loader → FAQ dataset: reads
- Response policy → Semantic retrieval: retrieves match
- Semantic retrieval → Text preprocessing: normalizes text
- Semantic retrieval → Sentence Transformer: encodes and scores
- Semantic retrieval → FAQ dataset: uses loaded rows
- Response policy → Runtime settings: reads settings
- HTTP routes → JSON responses: formats response
- HTTP routes → Structured logger: logs request
- Response policy → Structured logger: logs query
- Structured logger → Chat logs: writes events
- Flask app → HTTP routes: registers routes
- Flask app → Runtime settings: reads settings
- Flask app → Structured logger: configures logging
- Chat interface → Chat interaction: loads script
- Chat interaction → Browser storage: persists chat
- Chat interaction → Chat interface: updates interface
- Evaluation runner → Evaluation cases: reads cases
- Evaluation runner → Response policy: evaluates responses