# kakakaguya/calculus_ai_tutor architecture

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

- Interactive diagram: https://gitdiagram.com/kakakaguya/calculus_ai_tutor
- Repository: https://github.com/kakakaguya/calculus_ai_tutor

## Overview

This repository is a lightweight calculus Q&A tutor: the primary workflow is browser question → local web handler → Ollama answer (or demo fallback) → saved conversation history. It also includes a separate PDF-to-vector-store ingestion script and a standalone streaming model example. The README describes streaming, while the sampled web app uses a non-streaming Ollama request; the ingestion store is not connected to web answering in the inspected code.

Main entry points: [`web_app.py`](https://github.com/kakakaguya/calculus_ai_tutor/blob/main/web_app.py) (Question answering), [`ingest.py`](https://github.com/kakakaguya/calculus_ai_tutor/blob/main/ingest.py) (PDF extraction), [`calculus_tutor.db`](https://github.com/kakakaguya/calculus_ai_tutor/blob/main/calculus_tutor.db) (SQLite database), [`create_database.py`](https://github.com/kakakaguya/calculus_ai_tutor/blob/main/create_database.py) (Schema setup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web tutoring"]
  node_browser["Browser interface<br/>[web_app.py]"]
  node_http["HTTP handler<br/>[web_app.py]"]
  node_answer["Question answering<br/>[web_app.py]"]
  node_history_context["History context<br/>[web_app.py]"]
  node_ollama_call["Ollama request<br/>[web_app.py]"]
  node_demo["Demo fallback<br/>[web_app.py]"]
end

subgraph group_knowledge["Knowledge ingestion"]
  node_pdf["Calculus PDF"]
  node_pdf_loader["PDF extraction<br/>[ingest.py]"]
  node_chunks["Text chunks<br/>[ingest.py]"]
  node_embeddings["Ollama embeddings<br/>[ingest.py]"]
  node_vectorstore[("Chroma index<br/>[ingest.py]")]
end

subgraph group_storage["Models and storage"]
  node_record["QA records<br/>[web_app.py]"]
  node_sqlite[("SQLite database<br/>[calculus_tutor.db]")]
  node_schema["Schema setup<br/>[create_database.py]"]
  node_ollama{{"Ollama Qwen3"}}
  node_cli_example["Streaming example<br/>[main_rag.py]"]
end

node_learner(("Learner"))

node_learner -->|"asks"| node_browser
node_browser -->|"sends request"| node_http
node_http -->|"dispatches"| node_answer
node_http -->|"loads history"| node_history_context
node_answer -->|"builds context"| node_history_context
node_answer -->|"requests answer"| node_ollama_call
node_ollama_call -->|"HTTP chat"| node_ollama
node_answer -.->|"falls back"| node_demo
node_answer -->|"saves Q&amp;A"| node_record
node_history_context -->|"reads history"| node_record
node_record -->|"reads and writes"| node_sqlite
node_schema -->|"creates tables"| node_sqlite
node_pdf -->|"provides source"| node_pdf_loader
node_pdf_loader -->|"splits text"| node_chunks
node_chunks -->|"adds documents"| node_vectorstore
node_embeddings -->|"embeds documents"| node_vectorstore
node_cli_example -.->|"streams prompt"| node_ollama

click node_browser "https://github.com/kakakaguya/calculus_ai_tutor/blob/main/web_app.py"
click node_http "https://github.com/kakakaguya/calculus_ai_tutor/blob/main/web_app.py"
click node_answer "https://github.com/kakakaguya/calculus_ai_tutor/blob/main/web_app.py"
click node_history_context "https://github.com/kakakaguya/calculus_ai_tutor/blob/main/web_app.py"
click node_ollama_call "https://github.com/kakakaguya/calculus_ai_tutor/blob/main/web_app.py"
click node_demo "https://github.com/kakakaguya/calculus_ai_tutor/blob/main/web_app.py"
click node_record "https://github.com/kakakaguya/calculus_ai_tutor/blob/main/web_app.py"
click node_sqlite "https://github.com/kakakaguya/calculus_ai_tutor/blob/main/calculus_tutor.db"
click node_schema "https://github.com/kakakaguya/calculus_ai_tutor/blob/main/create_database.py"
click node_pdf_loader "https://github.com/kakakaguya/calculus_ai_tutor/blob/main/ingest.py"
click node_chunks "https://github.com/kakakaguya/calculus_ai_tutor/blob/main/ingest.py"
click node_embeddings "https://github.com/kakakaguya/calculus_ai_tutor/blob/main/ingest.py"
click node_vectorstore "https://github.com/kakakaguya/calculus_ai_tutor/blob/main/ingest.py"
click node_cli_example "https://github.com/kakakaguya/calculus_ai_tutor/blob/main/main_rag.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_browser,node_http,node_answer,node_history_context,node_ollama_call,node_demo toneBlue
class node_pdf,node_pdf_loader,node_chunks,node_embeddings,node_vectorstore toneAmber
class node_record,node_sqlite,node_schema,node_ollama,node_cli_example toneMint
class node_learner toneIndigo
```

## Components

### Web tutoring

- [Browser interface](https://github.com/kakakaguya/calculus_ai_tutor/blob/main/web_app.py): `web_app.py`
- [HTTP handler](https://github.com/kakakaguya/calculus_ai_tutor/blob/main/web_app.py): `web_app.py`
- [Question answering](https://github.com/kakakaguya/calculus_ai_tutor/blob/main/web_app.py): `web_app.py`
- [History context](https://github.com/kakakaguya/calculus_ai_tutor/blob/main/web_app.py): `web_app.py`
- [Ollama request](https://github.com/kakakaguya/calculus_ai_tutor/blob/main/web_app.py): `web_app.py`
- [Demo fallback](https://github.com/kakakaguya/calculus_ai_tutor/blob/main/web_app.py): `web_app.py`

### Knowledge ingestion

- **Calculus PDF**
- [PDF extraction](https://github.com/kakakaguya/calculus_ai_tutor/blob/main/ingest.py): `ingest.py`
- [Text chunks](https://github.com/kakakaguya/calculus_ai_tutor/blob/main/ingest.py): `ingest.py`
- [Ollama embeddings](https://github.com/kakakaguya/calculus_ai_tutor/blob/main/ingest.py): `ingest.py`
- [Chroma index](https://github.com/kakakaguya/calculus_ai_tutor/blob/main/ingest.py): `ingest.py`

### Models and storage

- [QA records](https://github.com/kakakaguya/calculus_ai_tutor/blob/main/web_app.py): `web_app.py`
- [SQLite database](https://github.com/kakakaguya/calculus_ai_tutor/blob/main/calculus_tutor.db): `calculus_tutor.db`
- [Schema setup](https://github.com/kakakaguya/calculus_ai_tutor/blob/main/create_database.py): `create_database.py`
- **Ollama Qwen3**
- [Streaming example](https://github.com/kakakaguya/calculus_ai_tutor/blob/main/main_rag.py): `main_rag.py`

### Other components

- **Learner**

## Connections

- Learner → Browser interface: asks
- Browser interface → HTTP handler: sends request
- HTTP handler → Question answering: dispatches
- HTTP handler → History context: loads history
- Question answering → History context: builds context
- Question answering → Ollama request: requests answer
- Ollama request → Ollama Qwen3: HTTP chat
- Question answering → Demo fallback: falls back
- Question answering → QA records: saves Q&A
- History context → QA records: reads history
- QA records → SQLite database: reads and writes
- Schema setup → SQLite database: creates tables
- Calculus PDF → PDF extraction: provides source
- PDF extraction → Text chunks: splits text
- Text chunks → Chroma index: adds documents
- Ollama embeddings → Chroma index: embeds documents
- Streaming example → Ollama Qwen3: streams prompt