# shonegk/chatterpy architecture

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

- Interactive diagram: https://gitdiagram.com/shonegk/chatterpy
- Repository: https://github.com/shonegk/chatterpy

## Overview

ChatterBot is a conversational engine that learns from stored conversation pairs and returns likely replies. The documented workflow accepts a user statement, searches known statements for a close match, selects a response, and saves the exchange for future learning; corpus trainers can seed that knowledge. Its logic adapters also provide specialized responses such as math, time, and unit conversion, while pluggable storage includes SQL, MongoDB, and Django backends. The map follows documented and excerpted relationships; unsampled modules are represented only where the tree and README establish their role.

Main entry points: [`chatterbot/storage/storage_adapter.py`](https://github.com/shonegk/chatterpy/blob/main/chatterbot/storage/storage_adapter.py) (Storage Interface), [`chatterbot/chatterbot.py`](https://github.com/shonegk/chatterpy/blob/main/chatterbot/chatterbot.py) (ChatBot), [`chatterbot/search.py`](https://github.com/shonegk/chatterpy/blob/main/chatterbot/search.py) (Text Search), [`chatterbot/logic/logic_adapter.py`](https://github.com/shonegk/chatterpy/blob/main/chatterbot/logic/logic_adapter.py) (Logic Adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_conversation["Conversation Runtime"]
  node_chatbot["ChatBot<br/>[chatterbot.py]"]
  node_statement["Statement Model<br/>[conversation.py]"]
  node_search["Text Search<br/>[search.py]"]
end

subgraph group_logic["Response Logic"]
  node_logic_adapter["Logic Adapter<br/>[logic_adapter.py]"]
  node_best_match["Best Match<br/>[best_match.py]"]
  node_special_logic["Specialized Logic"]
  node_response_selection["Response Selection"]
end

subgraph group_learning["Training and Language"]
  node_corpus["Corpus Loader<br/>[corpus.py]"]
  node_trainers["Corpus Trainers<br/>[trainers.py]"]
  node_tagger["Statement Tagger<br/>[tagging.py]"]
  node_languages["Language Registry<br/>[languages.py]"]
end

subgraph group_storage["Storage Backends"]
  node_storage_adapter["Storage Interface<br/>[storage_adapter.py]"]
  node_sql_storage["SQL Storage<br/>[sql_storage.py]"]
  node_mongo_storage["MongoDB Storage<br/>[mongodb.py]"]
  node_django_storage["Django Storage<br/>[django_storage.py]"]
end

subgraph group_integrations["Framework Integrations"]
  node_sql_models["SQL Models<br/>[models.py]"]
  node_django_models["Django Models<br/>[abstract_models.py]"]
end

node_user(("User"))

node_user -->|"submits statement"| node_chatbot
node_chatbot -->|"creates"| node_statement
node_chatbot -->|"dispatches to"| node_logic_adapter
node_chatbot -->|"persists through"| node_storage_adapter
node_chatbot -->|"configures"| node_search
node_logic_adapter -->|"searches with"| node_search
node_logic_adapter -->|"selects response"| node_response_selection
node_best_match -->|"extends"| node_logic_adapter
node_chatbot -->|"defaults to"| node_best_match
node_chatbot -->|"supports"| node_special_logic
node_search -->|"filters statements"| node_storage_adapter
node_search -->|"compares"| node_statement
node_trainers -->|"loads data"| node_corpus
node_trainers -.->|"adds statements"| node_storage_adapter
node_trainers -->|"uses tags"| node_tagger
node_storage_adapter -->|"initializes"| node_tagger
node_storage_adapter -->|"uses language"| node_languages
node_sql_storage -->|"implements"| node_storage_adapter
node_mongo_storage -->|"implements"| node_storage_adapter
node_django_storage -->|"implements"| node_storage_adapter
node_sql_storage -->|"creates tables"| node_sql_models
node_django_storage -.->|"loads models"| node_django_models

click node_chatbot "https://github.com/shonegk/chatterpy/blob/main/chatterbot/chatterbot.py"
click node_statement "https://github.com/shonegk/chatterpy/blob/main/chatterbot/conversation.py"
click node_search "https://github.com/shonegk/chatterpy/blob/main/chatterbot/search.py"
click node_logic_adapter "https://github.com/shonegk/chatterpy/blob/main/chatterbot/logic/logic_adapter.py"
click node_best_match "https://github.com/shonegk/chatterpy/blob/main/chatterbot/logic/best_match.py"
click node_special_logic "https://github.com/shonegk/chatterpy/tree/main/chatterbot/logic"
click node_response_selection "https://github.com/shonegk/chatterpy/blob/main/chatterbot/response_selection.py"
click node_corpus "https://github.com/shonegk/chatterpy/blob/main/chatterbot/corpus.py"
click node_trainers "https://github.com/shonegk/chatterpy/blob/main/chatterbot/trainers.py"
click node_tagger "https://github.com/shonegk/chatterpy/blob/main/chatterbot/tagging.py"
click node_languages "https://github.com/shonegk/chatterpy/blob/main/chatterbot/languages.py"
click node_storage_adapter "https://github.com/shonegk/chatterpy/blob/main/chatterbot/storage/storage_adapter.py"
click node_sql_storage "https://github.com/shonegk/chatterpy/blob/main/chatterbot/storage/sql_storage.py"
click node_mongo_storage "https://github.com/shonegk/chatterpy/blob/main/chatterbot/storage/mongodb.py"
click node_django_storage "https://github.com/shonegk/chatterpy/blob/main/chatterbot/storage/django_storage.py"
click node_sql_models "https://github.com/shonegk/chatterpy/blob/main/chatterbot/ext/sqlalchemy_app/models.py"
click node_django_models "https://github.com/shonegk/chatterpy/blob/main/chatterbot/ext/django_chatterbot/abstract_models.py"

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_chatbot,node_statement,node_search,node_user toneBlue
class node_logic_adapter,node_best_match,node_special_logic,node_response_selection toneAmber
class node_corpus,node_trainers,node_tagger,node_languages toneMint
class node_storage_adapter,node_sql_storage,node_mongo_storage,node_django_storage toneRose
class node_sql_models,node_django_models toneIndigo
```

## Components

### Conversation Runtime

- [ChatBot](https://github.com/shonegk/chatterpy/blob/main/chatterbot/chatterbot.py): `chatterbot/chatterbot.py`
- [Statement Model](https://github.com/shonegk/chatterpy/blob/main/chatterbot/conversation.py): `chatterbot/conversation.py`
- [Text Search](https://github.com/shonegk/chatterpy/blob/main/chatterbot/search.py): `chatterbot/search.py`

### Response Logic

- [Logic Adapter](https://github.com/shonegk/chatterpy/blob/main/chatterbot/logic/logic_adapter.py): `chatterbot/logic/logic_adapter.py`
- [Best Match](https://github.com/shonegk/chatterpy/blob/main/chatterbot/logic/best_match.py): `chatterbot/logic/best_match.py`
- [Specialized Logic](https://github.com/shonegk/chatterpy/tree/main/chatterbot/logic): `chatterbot/logic`
- [Response Selection](https://github.com/shonegk/chatterpy/blob/main/chatterbot/response_selection.py): `chatterbot/response_selection.py`

### Training and Language

- [Corpus Loader](https://github.com/shonegk/chatterpy/blob/main/chatterbot/corpus.py): `chatterbot/corpus.py`
- [Corpus Trainers](https://github.com/shonegk/chatterpy/blob/main/chatterbot/trainers.py): `chatterbot/trainers.py`
- [Statement Tagger](https://github.com/shonegk/chatterpy/blob/main/chatterbot/tagging.py): `chatterbot/tagging.py`
- [Language Registry](https://github.com/shonegk/chatterpy/blob/main/chatterbot/languages.py): `chatterbot/languages.py`

### Storage Backends

- [Storage Interface](https://github.com/shonegk/chatterpy/blob/main/chatterbot/storage/storage_adapter.py): `chatterbot/storage/storage_adapter.py`
- [SQL Storage](https://github.com/shonegk/chatterpy/blob/main/chatterbot/storage/sql_storage.py): `chatterbot/storage/sql_storage.py`
- [MongoDB Storage](https://github.com/shonegk/chatterpy/blob/main/chatterbot/storage/mongodb.py): `chatterbot/storage/mongodb.py`
- [Django Storage](https://github.com/shonegk/chatterpy/blob/main/chatterbot/storage/django_storage.py): `chatterbot/storage/django_storage.py`

### Framework Integrations

- [SQL Models](https://github.com/shonegk/chatterpy/blob/main/chatterbot/ext/sqlalchemy_app/models.py): `chatterbot/ext/sqlalchemy_app/models.py`
- [Django Models](https://github.com/shonegk/chatterpy/blob/main/chatterbot/ext/django_chatterbot/abstract_models.py): `chatterbot/ext/django_chatterbot/abstract_models.py`

### Other components

- **User**

## Connections

- User → ChatBot: submits statement (evidence: `README.md`)
- ChatBot → Statement Model: creates (evidence: `chatterbot/chatterbot.py`)
- ChatBot → Logic Adapter: dispatches to (evidence: `chatterbot/chatterbot.py`)
- ChatBot → Storage Interface: persists through (evidence: `chatterbot/chatterbot.py`)
- ChatBot → Text Search: configures (evidence: `chatterbot/chatterbot.py`)
- Logic Adapter → Text Search: searches with (evidence: `chatterbot/logic/logic_adapter.py`)
- Logic Adapter → Response Selection: selects response (evidence: `chatterbot/logic/logic_adapter.py`)
- Best Match → Logic Adapter: extends (evidence: `chatterbot/logic/best_match.py`)
- ChatBot → Best Match: defaults to (evidence: `chatterbot/chatterbot.py`)
- ChatBot → Specialized Logic: supports (evidence: `chatterbot/logic/__init__.py`)
- Text Search → Storage Interface: filters statements (evidence: `chatterbot/search.py`)
- Text Search → Statement Model: compares (evidence: `chatterbot/search.py`)
- Corpus Trainers → Corpus Loader: loads data (evidence: `chatterbot/trainers.py`)
- Corpus Trainers → Storage Interface: adds statements
- Corpus Trainers → Statement Tagger: uses tags (evidence: `chatterbot/trainers.py`)
- Storage Interface → Statement Tagger: initializes (evidence: `chatterbot/storage/storage_adapter.py`)
- Storage Interface → Language Registry: uses language (evidence: `chatterbot/storage/storage_adapter.py`)
- SQL Storage → Storage Interface: implements (evidence: `chatterbot/storage/sql_storage.py`)
- MongoDB Storage → Storage Interface: implements (evidence: `chatterbot/storage/mongodb.py`)
- Django Storage → Storage Interface: implements (evidence: `chatterbot/storage/django_storage.py`)
- SQL Storage → SQL Models: creates tables (evidence: `chatterbot/storage/sql_storage.py`)
- Django Storage → Django Models: loads models