How arpan8925/adhd-chatbot works
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 App entry · llms.py LLM layer · database.py SQLite layer · faiss_memory.py FAISS memory
Components 15
Presentation
User-facing request and rendering layer
AI Orchestration
Intent routing, generation, and semantic memory
- Trigger router · Detects greeting versus support branch
- Support branch · Negative-mood and routine check path
- Reply builder · Creates the conversational response
- LLM layer · Model integration for classification and generation
llms.py - Memory search · Searches prior chats by embedding similarity
- FAISS memory · Embedding-backed conversational memory
faiss_memory.py
Persistence
Structured state and long-term chat storage
- SQLite layer · Routine lookup and interaction persistence
database.py - Chat DB · Checked-in system of record for routine and history
adhd_assistant.db
Operations
Runtime logging, deployment, and dependency boundary
- Logger · Operational diagnostics and tracing
logger.py - Deploy config · Serverless deployment definition
vercel.json - Deps · Python dependency boundary
requirements.txt - Aux frontend · Non-core frontend dependencies/artifacts
chat-app/node_modules
Connections 17
- 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