# sirm00se/baseball-chatbot architecture

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

- Interactive diagram: https://gitdiagram.com/sirm00se/baseball-chatbot
- Repository: https://github.com/sirm00se/baseball-chatbot

## Overview

Baseball-Chatbot is a rules-focused RAG chatbot with a web interface and a documented older terminal client. The web workflow sends a question through FastAPI to the RAG engine, which rewrites it, retrieves rule chunks using embeddings and FAISS, fetches their metadata from SQLite, and asks Groq to generate an answer. Separate corpus-preparation paths scrape MLB glossary pages or chunk local rules documents, then build vector and SQL data. The excerpts show the web and retrieval links; some preparation details are supported by the README and source index rather than inspected call sites.

Main entry points: [`src/rag_engine.py`](https://github.com/sirm00se/baseball-chatbot/blob/master/src/rag_engine.py) (RAG engine), [`src/rebuildVectorDatabase.py`](https://github.com/sirm00se/baseball-chatbot/blob/master/src/rebuildVectorDatabase.py) (Database rebuild), [`src/vectordatabase.py`](https://github.com/sirm00se/baseball-chatbot/blob/master/src/vectordatabase.py) (Vector builder), [`src/AddBaseballRules.py`](https://github.com/sirm00se/baseball-chatbot/blob/master/src/AddBaseballRules.py) (Rules chunker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web interface"]
  node_chat_ui["Chat UI<br/>[chat.js]"]
  node_page["Chat page<br/>[index.html]"]
  node_api["FastAPI API<br/>[main.py]"]
end

subgraph group_rag["Answer retrieval"]
  node_engine["RAG engine<br/>[rag_engine.py]"]
  node_rewrite["Question rewrite<br/>[rag_engine.py]"]
  node_embedding["Query embedding<br/>[rag_engine.py]"]
  node_faiss["Vector search<br/>[rag_engine.py]"]
  node_index[("FAISS index<br/>[vector_index.faiss]")]
  node_metadata_query["Chunk lookup<br/>[rag_engine.py]"]
  node_sql_db[("Rules database")]
  node_prompt["RAG prompt<br/>[rag_engine.py]"]
end

subgraph group_corpus["Rule corpus"]
  node_scraper["Glossary scraper<br/>[dataScraper.py]"]
  node_rule_chunker["Rules chunker"]
  node_rule_text["Rules documents<br/>[BaseballRules.txt]"]
  node_terms_text["Terms document"]
  node_rules_csv["Rules CSV<br/>[baseballrules.csv]"]
  node_vector_builder["Vector builder<br/>[vectordatabase.py]"]
  node_vector_metadata["Vector metadata"]
  node_sql_builder["SQL conversion<br/>[SQLConversion.py]"]
  node_rebuild["Database rebuild"]
end

subgraph group_legacy["Terminal client"]
  node_terminal["Terminal question loop<br/>[answerQuestion.py]"]
end

node_user(("Chat user"))
node_groq{{"Groq LLM"}}
node_mlb{{"MLB glossary"}}
node_ollama{{"Ollama model"}}

node_user -->|"enters question"| node_chat_ui
node_chat_ui -->|"posts question"| node_api
node_api -->|"serves page"| node_page
node_api -->|"calls"| node_engine
node_engine -->|"rewrites"| node_rewrite
node_engine -->|"embeds query"| node_embedding
node_engine -->|"searches vectors"| node_faiss
node_faiss -->|"searches"| node_index
node_engine -->|"looks up chunks"| node_metadata_query
node_metadata_query -->|"queries"| node_sql_db
node_engine -->|"builds prompt"| node_prompt
node_engine -->|"requests completion"| node_groq
node_scraper -->|"fetches glossary"| node_mlb
node_scraper -->|"writes chunks"| node_rules_csv
node_rule_text -->|"reads rules"| node_rule_chunker
node_terms_text -->|"reads terms"| node_rule_chunker
node_rule_chunker -->|"appends chunks"| node_rules_csv
node_vector_builder -->|"loads chunks"| node_rules_csv
node_vector_builder -->|"writes index"| node_index
node_vector_builder -->|"writes metadata"| node_vector_metadata
node_sql_builder -->|"loads metadata"| node_vector_metadata
node_sql_builder -->|"writes rules table"| node_sql_db
node_rebuild -->|"runs"| node_scraper
node_rebuild -->|"runs"| node_rule_chunker
node_rebuild -->|"runs"| node_vector_builder
node_rebuild -->|"runs"| node_sql_builder
node_terminal -->|"requests answers"| node_ollama
node_terminal -->|"searches"| node_index
node_terminal -->|"queries chunks"| node_sql_db

click node_chat_ui "https://github.com/sirm00se/baseball-chatbot/blob/master/static/chat.js"
click node_page "https://github.com/sirm00se/baseball-chatbot/blob/master/static/index.html"
click node_api "https://github.com/sirm00se/baseball-chatbot/blob/master/src/main.py"
click node_engine "https://github.com/sirm00se/baseball-chatbot/blob/master/src/rag_engine.py"
click node_rewrite "https://github.com/sirm00se/baseball-chatbot/blob/master/src/rag_engine.py"
click node_embedding "https://github.com/sirm00se/baseball-chatbot/blob/master/src/rag_engine.py"
click node_faiss "https://github.com/sirm00se/baseball-chatbot/blob/master/src/rag_engine.py"
click node_index "https://github.com/sirm00se/baseball-chatbot/blob/master/databases/vector_index.faiss"
click node_metadata_query "https://github.com/sirm00se/baseball-chatbot/blob/master/src/rag_engine.py"
click node_sql_db "https://github.com/sirm00se/baseball-chatbot/blob/master/databases/baseball_vectors.db"
click node_prompt "https://github.com/sirm00se/baseball-chatbot/blob/master/src/rag_engine.py"
click node_scraper "https://github.com/sirm00se/baseball-chatbot/blob/master/src/dataScraper.py"
click node_rule_chunker "https://github.com/sirm00se/baseball-chatbot/blob/master/src/AddBaseballRules.py"
click node_rule_text "https://github.com/sirm00se/baseball-chatbot/blob/master/data/BaseballRules.txt"
click node_terms_text "https://github.com/sirm00se/baseball-chatbot/blob/master/data/Definition%20of%20Terms.txt"
click node_rules_csv "https://github.com/sirm00se/baseball-chatbot/blob/master/data/baseballrules.csv"
click node_vector_builder "https://github.com/sirm00se/baseball-chatbot/blob/master/src/vectordatabase.py"
click node_vector_metadata "https://github.com/sirm00se/baseball-chatbot/blob/master/data/vector_metadata.csv"
click node_sql_builder "https://github.com/sirm00se/baseball-chatbot/blob/master/src/SQLConversion.py"
click node_rebuild "https://github.com/sirm00se/baseball-chatbot/blob/master/src/rebuildVectorDatabase.py"
click node_terminal "https://github.com/sirm00se/baseball-chatbot/blob/master/src/answerQuestion.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_chat_ui,node_page,node_api,node_user toneBlue
class node_engine,node_rewrite,node_embedding,node_faiss,node_index,node_metadata_query,node_sql_db,node_prompt toneAmber
class node_scraper,node_rule_chunker,node_rule_text,node_terms_text,node_rules_csv,node_vector_builder,node_vector_metadata,node_sql_builder,node_rebuild toneMint
class node_terminal toneRose
class node_groq,node_mlb,node_ollama toneIndigo
```

## Components

### Web interface

- [Chat UI](https://github.com/sirm00se/baseball-chatbot/blob/master/static/chat.js): `static/chat.js`
- [Chat page](https://github.com/sirm00se/baseball-chatbot/blob/master/static/index.html): `static/index.html`
- [FastAPI API](https://github.com/sirm00se/baseball-chatbot/blob/master/src/main.py): `src/main.py`

### Answer retrieval

- [RAG engine](https://github.com/sirm00se/baseball-chatbot/blob/master/src/rag_engine.py): `src/rag_engine.py`
- [Question rewrite](https://github.com/sirm00se/baseball-chatbot/blob/master/src/rag_engine.py): `src/rag_engine.py`
- [Query embedding](https://github.com/sirm00se/baseball-chatbot/blob/master/src/rag_engine.py): `src/rag_engine.py`
- [Vector search](https://github.com/sirm00se/baseball-chatbot/blob/master/src/rag_engine.py): `src/rag_engine.py`
- [FAISS index](https://github.com/sirm00se/baseball-chatbot/blob/master/databases/vector_index.faiss): `databases/vector_index.faiss`
- [Chunk lookup](https://github.com/sirm00se/baseball-chatbot/blob/master/src/rag_engine.py): `src/rag_engine.py`
- [Rules database](https://github.com/sirm00se/baseball-chatbot/blob/master/databases/baseball_vectors.db): `databases/baseball_vectors.db`
- [RAG prompt](https://github.com/sirm00se/baseball-chatbot/blob/master/src/rag_engine.py): `src/rag_engine.py`

### Rule corpus

- [Glossary scraper](https://github.com/sirm00se/baseball-chatbot/blob/master/src/dataScraper.py): `src/dataScraper.py`
- [Rules chunker](https://github.com/sirm00se/baseball-chatbot/blob/master/src/AddBaseballRules.py): `src/AddBaseballRules.py`
- [Rules documents](https://github.com/sirm00se/baseball-chatbot/blob/master/data/BaseballRules.txt): `data/BaseballRules.txt`
- [Terms document](https://github.com/sirm00se/baseball-chatbot/blob/master/data/Definition%20of%20Terms.txt): `data/Definition of Terms.txt`
- [Rules CSV](https://github.com/sirm00se/baseball-chatbot/blob/master/data/baseballrules.csv): `data/baseballrules.csv`
- [Vector builder](https://github.com/sirm00se/baseball-chatbot/blob/master/src/vectordatabase.py): `src/vectordatabase.py`
- [Vector metadata](https://github.com/sirm00se/baseball-chatbot/blob/master/data/vector_metadata.csv): `data/vector_metadata.csv`
- [SQL conversion](https://github.com/sirm00se/baseball-chatbot/blob/master/src/SQLConversion.py): `src/SQLConversion.py`
- [Database rebuild](https://github.com/sirm00se/baseball-chatbot/blob/master/src/rebuildVectorDatabase.py): `src/rebuildVectorDatabase.py`

### Terminal client

- [Terminal question loop](https://github.com/sirm00se/baseball-chatbot/blob/master/src/answerQuestion.py): `src/answerQuestion.py`

### Other components

- **Chat user**
- **Groq LLM**
- **MLB glossary**
- **Ollama model**

## Connections

- Chat user → Chat UI: enters question (evidence: `static/chat.js`)
- Chat UI → FastAPI API: posts question (evidence: `static/chat.js`)
- FastAPI API → Chat page: serves page (evidence: `src/main.py`)
- FastAPI API → RAG engine: calls (evidence: `src/main.py`)
- RAG engine → Question rewrite: rewrites (evidence: `src/rag_engine.py`)
- RAG engine → Query embedding: embeds query (evidence: `src/rag_engine.py`)
- RAG engine → Vector search: searches vectors (evidence: `src/rag_engine.py`)
- Vector search → FAISS index: searches (evidence: `src/rag_engine.py`)
- RAG engine → Chunk lookup: looks up chunks (evidence: `src/rag_engine.py`)
- Chunk lookup → Rules database: queries (evidence: `src/rag_engine.py`)
- RAG engine → RAG prompt: builds prompt (evidence: `src/rag_engine.py`)
- RAG engine → Groq LLM: requests completion (evidence: `src/rag_engine.py`)
- Glossary scraper → MLB glossary: fetches glossary (evidence: `src/dataScraper.py`)
- Glossary scraper → Rules CSV: writes chunks (evidence: `src/dataScraper.py`)
- Rules documents → Rules chunker: reads rules (evidence: `src/AddBaseballRules.py`)
- Terms document → Rules chunker: reads terms (evidence: `src/AddBaseballRules.py`)
- Rules chunker → Rules CSV: appends chunks (evidence: `src/AddBaseballRules.py`)
- Vector builder → Rules CSV: loads chunks (evidence: `src/vectordatabase.py`)
- Vector builder → FAISS index: writes index (evidence: `src/vectordatabase.py`)
- Vector builder → Vector metadata: writes metadata (evidence: `src/vectordatabase.py`)
- SQL conversion → Vector metadata: loads metadata (evidence: `src/SQLConversion.py`)
- SQL conversion → Rules database: writes rules table (evidence: `src/SQLConversion.py`)
- Database rebuild → Glossary scraper: runs (evidence: `src/rebuildVectorDatabase.py`)
- Database rebuild → Rules chunker: runs (evidence: `src/rebuildVectorDatabase.py`)
- Database rebuild → Vector builder: runs (evidence: `src/rebuildVectorDatabase.py`)
- Database rebuild → SQL conversion: runs (evidence: `src/rebuildVectorDatabase.py`)
- Terminal question loop → Ollama model: requests answers (evidence: `src/answerQuestion.py`)
- Terminal question loop → FAISS index: searches (evidence: `src/answerQuestion.py`)
- Terminal question loop → Rules database: queries chunks (evidence: `src/answerQuestion.py`)
