# arpan8925/adhd-chatbot architecture

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

- Interactive diagram: https://gitdiagram.com/arpan8925/adhd-chatbot
- Repository: https://github.com/arpan8925/adhd-chatbot

## Overview

1. This repository is a small Python-backed AI chatbot application centered on one conversation workflow: user message in, NLP routing and context lookup, response generation, then persistence of both the interaction and its memory signals.

2. The main application entrypoint is `index.py`. The presence of `templates/index.html` suggests the user-facing layer is server-rendered HTML rather than a separate SPA, with `index.py` likely handling request routing, form submission, and response rendering.

3. The core AI/NLP subsystem is split into `llms.py` and `faiss_memory.py`. `llms.py` is the language-model integration layer, using Gemini and LangChain for intent handling and response generation. `faiss_memory.py` provides semantic memory via FAISS, so prior chats can be embedded and searched rather than stored only as raw text.

4. State and domain data live in SQLite, via `database.py` and the checked-in `adhd_assistant.db`. This is the system of record for user-related routine data and interaction logs, and it is used by the “depression / routine check” branch described in the README.

5. The main decision flow is: input arrives → lightweight trigger detection and NLP classification → either basic greeting handling or a mental-state/routine support branch. The README indicates triggers such as “depressed,” “sad,” “hopeless,” and “overwhelmed” are used to route into a more supportive path.

6. When a negative mood trigger is detected, the app queries SQLite for routine indicators such as sleep duration and meal timing, then compares them to ADHD-specific thresholds. That comparison drives whether the bot returns targeted guidance for sleep, nutrition, and movement or falls back to more general coping advice.

7. Interaction persistence is intentionally duplicated across two stores: SQLite for structured history and FAISS for semantic retrieval. The README’s logging flow shows that each user message and bot reply are inserted into the database and also added as embeddings, which creates both auditability and long-term conversational memory.

8. `logger.py` is the operational cross-cutting layer for runtime logging. It is separate from user interaction logging and is likely used for application diagnostics, errors, and request tracing.

9. The `templates/` directory represents the presentation boundary, while the backend modules represent three distinct domains: web/UI, AI reasoning, and persistent memory/data. This separation is important for the architecture diagram because the chatbot’s intelligence is not embedded in the template layer; it is mediated by Python services.

10. Operationally, the repo is packaged for deployment with `vercel.json`, which implies the app is intended to run in a serverless or managed hosting environment. The presence of `requirements.txt` confirms the Python dependency boundary, while the `chat-app/node_modules` directory looks like an auxiliary frontend artifact rather than the architectural core.

11. The most important data flow to diagram is: browser/UI → `index.py` → `llms.py` for routing/generation → `database.py` for routine lookup and logging → `faiss_memory.py` for semantic memory updates → response back to the UI. That flow captures the repository’s actual behavior better than a generic chatbot diagram.

12. In short, the system is a Python monolith with three major subsystems: a thin web interface, an AI orchestration layer built on Gemini/LangChain plus FAISS, and a SQLite-backed persistence layer for user routine state and interaction history.

Main entry points: [`index.py`](https://github.com/arpan8925/adhd-chatbot/blob/main/index.py) (App entry), [`llms.py`](https://github.com/arpan8925/adhd-chatbot/blob/main/llms.py) (LLM layer), [`database.py`](https://github.com/arpan8925/adhd-chatbot/blob/main/database.py) (SQLite layer), [`faiss_memory.py`](https://github.com/arpan8925/adhd-chatbot/blob/main/faiss_memory.py) (FAISS memory)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_presentation["Presentation"]
  node_client(("Browser<br/>user"))
  node_index_py["App entry<br/>web handler<br/>[index.py]"]
  node_template_html["Chat page<br/>server template<br/>[index.html]"]
end

subgraph group_ai["AI Orchestration"]
  node_trigger_router{{"Trigger router<br/>nlp routing"}}
  node_support_branch{{"Support branch<br/>routine logic"}}
  node_response_gen{{"Reply builder<br/>generation flow"}}
  node_llms_py["LLM layer<br/>gemini/langchain<br/>[llms.py]"]
  node_memory_lookup{{"Memory search<br/>semantic retrieval"}}
  node_faiss_py[("FAISS memory<br/>vector store<br/>[faiss_memory.py]")]
end

subgraph group_data["Persistence"]
  node_database_py["SQLite layer<br/>data access<br/>[database.py]"]
  node_chat_db[("Chat DB<br/>sqlite database<br/>[adhd_assistant.db]")]
end

subgraph group_ops["Operations"]
  node_logger_py["Logger<br/>runtime logging<br/>[logger.py]"]
  node_vercel_json["Deploy config<br/>hosting config<br/>[vercel.json]"]
  node_requirements_txt["Deps<br/>python requirements<br/>[requirements.txt]"]
  node_node_modules["Aux frontend<br/>auxiliary artifact"]
end

node_client -->|"send message"| node_index_py
node_index_py -->|"render"| node_template_html
node_index_py -->|"route intent"| node_trigger_router
node_trigger_router -->|"classify"| node_llms_py
node_trigger_router -->|"support path"| node_support_branch
node_support_branch -->|"lookup routine"| node_database_py
node_support_branch -->|"shape guidance"| node_response_gen
node_response_gen -->|"generate reply"| node_llms_py
node_llms_py -->|"consult memory"| node_memory_lookup
node_memory_lookup -->|"search embeddings"| node_faiss_py
node_index_py -->|"persist chat"| node_database_py
node_database_py -->|"read/write"| node_chat_db
node_index_py -->|"store memory"| node_faiss_py
node_index_py -->|"log events"| node_logger_py
node_index_py -.->|"deploy target"| node_vercel_json
node_index_py -.->|"depends on"| node_requirements_txt
node_index_py -.->|"auxiliary"| node_node_modules

click node_index_py "https://github.com/arpan8925/adhd-chatbot/blob/main/index.py"
click node_template_html "https://github.com/arpan8925/adhd-chatbot/blob/main/templates/index.html"
click node_llms_py "https://github.com/arpan8925/adhd-chatbot/blob/main/llms.py"
click node_faiss_py "https://github.com/arpan8925/adhd-chatbot/blob/main/faiss_memory.py"
click node_database_py "https://github.com/arpan8925/adhd-chatbot/blob/main/database.py"
click node_chat_db "https://github.com/arpan8925/adhd-chatbot/blob/main/adhd_assistant.db"
click node_logger_py "https://github.com/arpan8925/adhd-chatbot/blob/main/logger.py"
click node_vercel_json "https://github.com/arpan8925/adhd-chatbot/blob/main/vercel.json"
click node_requirements_txt "https://github.com/arpan8925/adhd-chatbot/blob/main/requirements.txt"
click node_node_modules "https://github.com/arpan8925/adhd-chatbot/tree/main/chat-app/node_modules"

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_client,node_index_py,node_template_html toneBlue
class node_trigger_router,node_support_branch,node_response_gen,node_llms_py,node_memory_lookup,node_faiss_py toneAmber
class node_database_py,node_chat_db toneMint
class node_logger_py,node_vercel_json,node_requirements_txt,node_node_modules toneRose
```

## Components

### Presentation

User-facing request and rendering layer

- **Browser**: user · Chat input and rendered replies
- [App entry](https://github.com/arpan8925/adhd-chatbot/blob/main/index.py): web handler · Main request routing and response assembly · `index.py`
- [Chat page](https://github.com/arpan8925/adhd-chatbot/blob/main/templates/index.html): server template · Rendered HTML chat interface · `templates/index.html`

### AI Orchestration

Intent routing, generation, and semantic memory

- **Trigger router**: nlp routing · Detects greeting versus support branch
- **Support branch**: routine logic · Negative-mood and routine check path
- **Reply builder**: generation flow · Creates the conversational response
- [LLM layer](https://github.com/arpan8925/adhd-chatbot/blob/main/llms.py): gemini/langchain · Model integration for classification and generation · `llms.py`
- **Memory search**: semantic retrieval · Searches prior chats by embedding similarity
- [FAISS memory](https://github.com/arpan8925/adhd-chatbot/blob/main/faiss_memory.py): vector store · Embedding-backed conversational memory · `faiss_memory.py`

### Persistence

Structured state and long-term chat storage

- [SQLite layer](https://github.com/arpan8925/adhd-chatbot/blob/main/database.py): data access · Routine lookup and interaction persistence · `database.py`
- [Chat DB](https://github.com/arpan8925/adhd-chatbot/blob/main/adhd_assistant.db): sqlite database · Checked-in system of record for routine and history · `adhd_assistant.db`

### Operations

Runtime logging, deployment, and dependency boundary

- [Logger](https://github.com/arpan8925/adhd-chatbot/blob/main/logger.py): runtime logging · Operational diagnostics and tracing · `logger.py`
- [Deploy config](https://github.com/arpan8925/adhd-chatbot/blob/main/vercel.json): hosting config · Serverless deployment definition · `vercel.json`
- [Deps](https://github.com/arpan8925/adhd-chatbot/blob/main/requirements.txt): python requirements · Python dependency boundary · `requirements.txt`
- [Aux frontend](https://github.com/arpan8925/adhd-chatbot/tree/main/chat-app/node_modules): auxiliary artifact · Non-core frontend dependencies/artifacts · `chat-app/node_modules`

## Connections

- Browser → App entry: send message · User submits chat input to the app
- App entry → Chat page: render · Server returns the HTML chat view
- App entry → Trigger router: route intent · Entrypoint delegates message classification
- Trigger router → LLM layer: classify · Uses the model layer for NLP handling
- Trigger router → Support branch: support path · Routes negative mood messages to routine checks
- Support branch → SQLite layer: lookup routine · Reads sleep, meals, and other indicators
- Support branch → Reply builder: shape guidance · Combines routine context with advice selection
- Reply builder → LLM layer: generate reply · Produces the final chatbot response
- LLM layer → Memory search: consult memory · Fetches relevant prior context
- Memory search → FAISS memory: search embeddings · Queries the vector-backed semantic store
- App entry → SQLite layer: persist chat · Stores interaction history and routine data
- SQLite layer → Chat DB: read/write · Structured persistence in SQLite
- App entry → FAISS memory: store memory · Adds user and bot messages as embeddings
- App entry → Logger: log events · Records runtime diagnostics and errors
- App entry → Deploy config: deploy target · Hosted as a managed/serverless app
- App entry → Deps: depends on · Python runtime dependency boundary
- App entry → Aux frontend: auxiliary · Non-core frontend artifact present in repo
