# rohannx29/ai-learner architecture

> Architecture diagram of the GitHub repository rohannx29/ai-learner, 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/rohannx29/ai-learner
- Repository: https://github.com/rohannx29/ai-learner

## Overview

AI-Learner is a web-based learning assistant. Users interact through a Next.js frontend; the FastAPI application routes requests to account, notes, RAG, tutor, roadmap, and explanation features. The documented study-material workflow processes uploads into chunks and vector storage, then retrieves and reranks notes to ground AI answers. The graph includes that ingestion path and the symbolic-math branch. Some subsystem links rely on README documentation or source-index references; unsampled implementation details are not inferred.

Main entry points: [`app/main.py`](https://github.com/rohannx29/ai-learner/blob/main/app/main.py) (FastAPI application), [`app/ai_engine/rag_engine.py`](https://github.com/rohannx29/ai-learner/blob/main/app/ai_engine/rag_engine.py) (Notes answer engine), [`app/auth/dependencies.py`](https://github.com/rohannx29/ai-learner/blob/main/app/auth/dependencies.py) (Token verification), [`app/api/notes_api.py`](https://github.com/rohannx29/ai-learner/blob/main/app/api/notes_api.py) (Notes upload routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web frontend"]
  node_web["Next.js interface"]
  node_api_client["API client<br/>[api.js]"]
end

subgraph group_api["API and identity"]
  node_app["FastAPI application<br/>[main.py]"]
  node_auth_api["Account routes<br/>[auth_api.py]"]
  node_auth_utils["Password and tokens<br/>[auth_utils.py]"]
  node_auth_guard["Token verification<br/>[dependencies.py]"]
end

subgraph group_learning["Learning features"]
  node_explain_api["Explanation route<br/>[explain_api.py]"]
  node_notes_api["Notes upload routes<br/>[notes_api.py]"]
  node_rag_api["Notes question route<br/>[rag_api.py]"]
  node_tutor_api["Tutor route<br/>[tutor_api.py]"]
  node_roadmap_api["Roadmap route<br/>[roadmap_api.py]"]
  node_rag_engine["Notes answer engine<br/>[rag_engine.py]"]
  node_math_engine["Symbolic solver<br/>[math_engine.py]"]
  node_prompts["Numerical prompt<br/>[math_prompts.py]"]
  node_llm["LLM generation<br/>[llm_engine.py]"]
  node_tutor_engine["Tutor chat engine<br/>[tutor_engine.py]"]
  node_roadmap_engine["Roadmap generator<br/>[roadmap_engine.py]"]
end

subgraph group_data["Processing and storage"]
  node_document_reader["Document extraction<br/>[document_reader.py]"]
  node_ocr["Math OCR<br/>[math_ocr.py]"]
  node_chunker["Text chunking<br/>[text_chunker.py]"]
  node_vector_db[("Vector retrieval<br/>[vector_db.py]")]
  node_db[("Relational database<br/>[database.py]")]
  node_models["User model<br/>[models.py]"]
end

node_learner(("Learner"))
node_ollama["Ollama model service"]
node_chroma[("ChromaDB")]

node_learner -->|"uses"| node_web
node_web -.->|"requests through"| node_api_client
node_api_client -->|"sends requests"| node_app
node_app -->|"registers"| node_auth_api
node_app -->|"registers"| node_explain_api
node_app -->|"registers"| node_notes_api
node_app -->|"registers"| node_rag_api
node_app -->|"registers"| node_roadmap_api
node_app -->|"registers"| node_tutor_api
node_auth_api -->|"uses"| node_auth_utils
node_auth_api -->|"queries and writes"| node_db
node_db -->|"creates tables"| node_models
node_notes_api -->|"requires identity"| node_auth_guard
node_rag_api -->|"requires identity"| node_auth_guard
node_tutor_api -->|"requires identity"| node_auth_guard
node_roadmap_api -->|"requires identity"| node_auth_guard
node_explain_api -->|"requires identity"| node_auth_guard
node_notes_api -->|"chunks text"| node_chunker
node_notes_api -->|"stores chunks"| node_vector_db
node_document_reader -->|"uses"| node_ocr
node_learner -->|"uploads material"| node_document_reader
node_document_reader -->|"extracts for chunking"| node_chunker
node_chunker -->|"prepares embeddings"| node_vector_db
node_vector_db -->|"persists and retrieves"| node_chroma
node_rag_api -->|"calls"| node_rag_engine
node_rag_engine -->|"queries chunks"| node_vector_db
node_rag_engine -->|"tries symbolic solve"| node_math_engine
node_rag_engine -->|"formats math prompt"| node_prompts
node_rag_engine -->|"generates answer"| node_llm
node_llm -->|"sends prompt"| node_ollama
node_tutor_api -->|"calls"| node_tutor_engine
node_tutor_engine -->|"chats with"| node_ollama
node_roadmap_api -->|"calls"| node_roadmap_engine
node_roadmap_engine -->|"generates with"| node_ollama
node_explain_api -->|"requests explanation"| node_llm

click node_web "https://github.com/rohannx29/ai-learner/tree/main/frontend-next/src/app"
click node_api_client "https://github.com/rohannx29/ai-learner/blob/main/frontend-next/src/lib/api.js"
click node_app "https://github.com/rohannx29/ai-learner/blob/main/app/main.py"
click node_auth_api "https://github.com/rohannx29/ai-learner/blob/main/app/api/auth_api.py"
click node_auth_utils "https://github.com/rohannx29/ai-learner/blob/main/app/auth/auth_utils.py"
click node_auth_guard "https://github.com/rohannx29/ai-learner/blob/main/app/auth/dependencies.py"
click node_explain_api "https://github.com/rohannx29/ai-learner/blob/main/app/api/explain_api.py"
click node_notes_api "https://github.com/rohannx29/ai-learner/blob/main/app/api/notes_api.py"
click node_rag_api "https://github.com/rohannx29/ai-learner/blob/main/app/api/rag_api.py"
click node_tutor_api "https://github.com/rohannx29/ai-learner/blob/main/app/api/tutor_api.py"
click node_roadmap_api "https://github.com/rohannx29/ai-learner/blob/main/app/api/roadmap_api.py"
click node_rag_engine "https://github.com/rohannx29/ai-learner/blob/main/app/ai_engine/rag_engine.py"
click node_math_engine "https://github.com/rohannx29/ai-learner/blob/main/app/ai_engine/math_engine.py"
click node_prompts "https://github.com/rohannx29/ai-learner/blob/main/app/ai_engine/math_prompts.py"
click node_llm "https://github.com/rohannx29/ai-learner/blob/main/app/ai_engine/llm_engine.py"
click node_tutor_engine "https://github.com/rohannx29/ai-learner/blob/main/app/ai_engine/tutor_engine.py"
click node_roadmap_engine "https://github.com/rohannx29/ai-learner/blob/main/app/ai_engine/roadmap_engine.py"
click node_document_reader "https://github.com/rohannx29/ai-learner/blob/main/app/utils/document_reader.py"
click node_ocr "https://github.com/rohannx29/ai-learner/blob/main/app/utils/math_ocr.py"
click node_chunker "https://github.com/rohannx29/ai-learner/blob/main/app/utils/text_chunker.py"
click node_vector_db "https://github.com/rohannx29/ai-learner/blob/main/app/ai_engine/vector_db.py"
click node_db "https://github.com/rohannx29/ai-learner/blob/main/app/db/database.py"
click node_models "https://github.com/rohannx29/ai-learner/blob/main/app/db/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_web,node_api_client toneBlue
class node_app,node_auth_api,node_auth_utils,node_auth_guard,node_chroma toneAmber
class node_explain_api,node_notes_api,node_rag_api,node_tutor_api,node_roadmap_api,node_rag_engine,node_math_engine,node_prompts,node_llm,node_tutor_engine,node_roadmap_engine toneMint
class node_document_reader,node_ocr,node_chunker,node_vector_db,node_db,node_models toneRose
class node_learner,node_ollama toneIndigo
```

## Components

### Web frontend

- [Next.js interface](https://github.com/rohannx29/ai-learner/tree/main/frontend-next/src/app): `frontend-next/src/app`
- [API client](https://github.com/rohannx29/ai-learner/blob/main/frontend-next/src/lib/api.js): `frontend-next/src/lib/api.js`

### API and identity

- [FastAPI application](https://github.com/rohannx29/ai-learner/blob/main/app/main.py): `app/main.py`
- [Account routes](https://github.com/rohannx29/ai-learner/blob/main/app/api/auth_api.py): `app/api/auth_api.py`
- [Password and tokens](https://github.com/rohannx29/ai-learner/blob/main/app/auth/auth_utils.py): `app/auth/auth_utils.py`
- [Token verification](https://github.com/rohannx29/ai-learner/blob/main/app/auth/dependencies.py): `app/auth/dependencies.py`

### Learning features

- [Explanation route](https://github.com/rohannx29/ai-learner/blob/main/app/api/explain_api.py): `app/api/explain_api.py`
- [Notes upload routes](https://github.com/rohannx29/ai-learner/blob/main/app/api/notes_api.py): `app/api/notes_api.py`
- [Notes question route](https://github.com/rohannx29/ai-learner/blob/main/app/api/rag_api.py): `app/api/rag_api.py`
- [Tutor route](https://github.com/rohannx29/ai-learner/blob/main/app/api/tutor_api.py): `app/api/tutor_api.py`
- [Roadmap route](https://github.com/rohannx29/ai-learner/blob/main/app/api/roadmap_api.py): `app/api/roadmap_api.py`
- [Notes answer engine](https://github.com/rohannx29/ai-learner/blob/main/app/ai_engine/rag_engine.py): `app/ai_engine/rag_engine.py`
- [Symbolic solver](https://github.com/rohannx29/ai-learner/blob/main/app/ai_engine/math_engine.py): `app/ai_engine/math_engine.py`
- [Numerical prompt](https://github.com/rohannx29/ai-learner/blob/main/app/ai_engine/math_prompts.py): `app/ai_engine/math_prompts.py`
- [LLM generation](https://github.com/rohannx29/ai-learner/blob/main/app/ai_engine/llm_engine.py): `app/ai_engine/llm_engine.py`
- [Tutor chat engine](https://github.com/rohannx29/ai-learner/blob/main/app/ai_engine/tutor_engine.py): `app/ai_engine/tutor_engine.py`
- [Roadmap generator](https://github.com/rohannx29/ai-learner/blob/main/app/ai_engine/roadmap_engine.py): `app/ai_engine/roadmap_engine.py`

### Processing and storage

- [Document extraction](https://github.com/rohannx29/ai-learner/blob/main/app/utils/document_reader.py): `app/utils/document_reader.py`
- [Math OCR](https://github.com/rohannx29/ai-learner/blob/main/app/utils/math_ocr.py): `app/utils/math_ocr.py`
- [Text chunking](https://github.com/rohannx29/ai-learner/blob/main/app/utils/text_chunker.py): `app/utils/text_chunker.py`
- [Vector retrieval](https://github.com/rohannx29/ai-learner/blob/main/app/ai_engine/vector_db.py): `app/ai_engine/vector_db.py`
- [Relational database](https://github.com/rohannx29/ai-learner/blob/main/app/db/database.py): `app/db/database.py`
- [User model](https://github.com/rohannx29/ai-learner/blob/main/app/db/models.py): `app/db/models.py`

### Other components

- **Learner**
- **Ollama model service**
- **ChromaDB**

## Connections

- Learner → Next.js interface: uses (evidence: `README.md`)
- Next.js interface → API client: requests through
- API client → FastAPI application: sends requests (evidence: `README.md`)
- FastAPI application → Account routes: registers (evidence: `app/main.py`)
- FastAPI application → Explanation route: registers (evidence: `app/main.py`)
- FastAPI application → Notes upload routes: registers (evidence: `app/main.py`)
- FastAPI application → Notes question route: registers (evidence: `app/main.py`)
- FastAPI application → Roadmap route: registers (evidence: `app/main.py`)
- FastAPI application → Tutor route: registers (evidence: `app/main.py`)
- Account routes → Password and tokens: uses (evidence: `app/api/auth_api.py`)
- Account routes → Relational database: queries and writes (evidence: `app/api/auth_api.py`)
- Relational database → User model: creates tables (evidence: `app/main.py`)
- Notes upload routes → Token verification: requires identity (evidence: `app/api/notes_api.py`)
- Notes question route → Token verification: requires identity (evidence: `app/api/rag_api.py`)
- Tutor route → Token verification: requires identity (evidence: `app/api/tutor_api.py`)
- Roadmap route → Token verification: requires identity (evidence: `app/api/roadmap_api.py`)
- Explanation route → Token verification: requires identity (evidence: `app/api/explain_api.py`)
- Notes upload routes → Text chunking: chunks text (evidence: `app/api/notes_api.py`)
- Notes upload routes → Vector retrieval: stores chunks (evidence: `app/api/notes_api.py`)
- Document extraction → Math OCR: uses (evidence: `app/utils/document_reader.py`)
- Learner → Document extraction: uploads material (evidence: `README.md`)
- Document extraction → Text chunking: extracts for chunking (evidence: `README.md`)
- Text chunking → Vector retrieval: prepares embeddings (evidence: `README.md`)
- Vector retrieval → ChromaDB: persists and retrieves (evidence: `README.md`)
- Notes question route → Notes answer engine: calls (evidence: `app/api/rag_api.py`)
- Notes answer engine → Vector retrieval: queries chunks (evidence: `app/ai_engine/rag_engine.py`)
- Notes answer engine → Symbolic solver: tries symbolic solve (evidence: `app/ai_engine/rag_engine.py`)
- Notes answer engine → Numerical prompt: formats math prompt (evidence: `app/ai_engine/rag_engine.py`)
- Notes answer engine → LLM generation: generates answer (evidence: `app/ai_engine/rag_engine.py`)
- LLM generation → Ollama model service: sends prompt (evidence: `app/ai_engine/llm_engine.py`)
- Tutor route → Tutor chat engine: calls (evidence: `app/api/tutor_api.py`)
- Tutor chat engine → Ollama model service: chats with (evidence: `app/ai_engine/tutor_engine.py`)
- Roadmap route → Roadmap generator: calls (evidence: `app/api/roadmap_api.py`)
- Roadmap generator → Ollama model service: generates with (evidence: `app/ai_engine/roadmap_engine.py`)
- Explanation route → LLM generation: requests explanation (evidence: `app/api/explain_api.py`)
