# princ3kr/notebook-lm-mini architecture

> Architecture diagram of the GitHub repository princ3kr/notebook-lm-mini, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/princ3kr/notebook-lm-mini
- Repository: https://github.com/princ3kr/notebook-lm-mini

## Overview

1. This repository is an AI tutoring system centered on a technical knowledge graph. The main runtime is Python, with a Streamlit UI entrypoint in `app.py`, and the core application logic split into services under `src/services`.

2. The project has two major phases: content ingestion and interactive tutoring. Ingestion turns a PDF textbook chapter into structured concept data; tutoring uses that structure to guide a student through a personalized learning path.

3. `src/services/pdf_service.py` is the document intake boundary. From the README, it converts PDFs into clean text/Markdown, chunks the content, and prepares it for downstream extraction. This is the first step that transforms unstructured textbook content into machine-readable units.

4. `src/services/llm_service.py` is the LLM integration layer. The README indicates Groq is used for extraction and pedagogical reasoning, so this service likely centralizes model calls and prompt/response handling rather than letting the rest of the code talk to the LLM directly.

5. The concept and learning-state domain is modeled in `src/models/`. `concept.py`, `diagnoses.py`, `intent.py`, and `state.py` suggest typed schemas for extracted concepts, quiz/diagnostic results, parsed student intent, and session state. This is the main consistency boundary between LLM output, graph storage, and tutoring logic.

6. `src/services/graph_service.py` is the knowledge-graph boundary. The README says concepts and relationships are stored in Neo4j, so this service likely owns graph construction, traversal, and lookup operations such as prerequisites, subtopics, and related concepts.

7. `src/database/neo4j_conn.py` is the infrastructure adapter for Neo4j connectivity. It isolates database configuration and session management from the rest of the system, keeping graph operations in `graph_service.py` and connection details in the database layer.

8. Student progress persistence is separated from the concept graph. `src/database/student_db.py` likely manages per-user/session data such as mastery scores, prior answers, and learning history; the README describes this as TinyDB-backed session management, so this is the stateful memory of the tutor while Neo4j is the shared knowledge base.

9. The tutoring workflow is split into distinct services: `intent_service.py` parses what the learner is asking for, `planner_service.py` chooses a learning path, `diagnoser_service.py` evaluates understanding, and `tutor_service.py` coordinates the actual teaching loop. This separation is important: intent, planning, assessment, and explanation are different responsibilities.

10. `src/services/tutor_lesson_utils.py` appears to hold helper logic shared by lesson delivery and remediation. In architectural terms, this is a support layer for composing lesson steps rather than a primary subsystem.

11. The end-to-end data flow is: PDF upload → text/chunk extraction → concept and relationship extraction → validation into structured JSON/models → Neo4j graph ingestion → student request parsing → path planning based on mastery and graph structure → diagnostic questioning → tutoring/remediation → session state persistence.

12. The repository also includes `py-notebook/` with concept JSON files and a notebook, which looks like an experimentation and inspection area for graph/content processing. `assets/workflow.svg` is a documentation artifact for the system diagram rather than part of runtime execution.

13. Overall, the main architectural boundaries are: UI vs. orchestration, unstructured document processing vs. structured graph storage, shared knowledge graph vs. per-student session memory, and model/LLM output vs. validated domain schemas. That separation is what makes the tutoring flow adaptive and reproducible.

Main entry points: [`src/services/tutor_service.py`](https://github.com/princ3kr/notebook-lm-mini/blob/main/src/services/tutor_service.py) (Tutor Core), [`src/services/planner_service.py`](https://github.com/princ3kr/notebook-lm-mini/blob/main/src/services/planner_service.py) (Planner), [`src/services/llm_service.py`](https://github.com/princ3kr/notebook-lm-mini/blob/main/src/services/llm_service.py) (LLM Gateway), [`src/services/diagnoser_service.py`](https://github.com/princ3kr/notebook-lm-mini/blob/main/src/services/diagnoser_service.py) (Diagnoser)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["UI"]
  node_app["App<br/>streamlit entrypoint<br/>[app.py]"]
end

subgraph group_ingestion["Ingestion"]
  node_pdf_service["PDF Intake<br/>document pipeline<br/>[pdf_service.py]"]
  node_llm_service{{"LLM Gateway<br/>model adapter<br/>[llm_service.py]"}}
  node_graph_service[("Graph Service<br/>knowledge graph<br/>[graph_service.py]")]
end

subgraph group_tutoring["Tutoring"]
  node_intent_service{{"Intent Service<br/>request parser<br/>[intent_service.py]"}}
  node_planner_service{{"Planner<br/>learning path<br/>[planner_service.py]"}}
  node_diagnoser_service{{"Diagnoser<br/>assessment loop"}}
  node_tutor_service["Tutor Core<br/>orchestrator<br/>[tutor_service.py]"]
  node_tutor_utils["Lesson Utils<br/>support logic"]
end

subgraph group_data["Data"]
  node_concept_model["Concepts<br/>domain schema<br/>[concept.py]"]
  node_neo4j_conn[("Neo4j Conn<br/>db adapter<br/>[neo4j_conn.py]")]
  node_student_db[("Student DB<br/>session store<br/>[student_db.py]")]
  node_intent_model["Intent<br/>domain schema<br/>[intent.py]"]
  node_state_model["Session State<br/>domain schema<br/>[state.py]"]
  node_diagnoses_model["Diagnoses<br/>domain schema<br/>[diagnoses.py]"]
end

subgraph group_experiments["Experiments"]
  node_concepts_json["Concept JSON<br/>sample data<br/>[concepts.json]"]
  node_notebook["Notebook<br/>[testing.ipynb]"]
end

node_app -->|"ingest content"| node_pdf_service
node_app -->|"start tutoring"| node_tutor_service
node_pdf_service -->|"extract structure"| node_llm_service
node_llm_service -->|"populate"| node_concept_model
node_concept_model -->|"load graph"| node_graph_service
node_graph_service -->|"persist/query"| node_neo4j_conn
node_intent_service -->|"parse intent"| node_llm_service
node_intent_service -->|"validate"| node_intent_model
node_tutor_service -->|"understand request"| node_intent_service
node_tutor_service -->|"plan path"| node_planner_service
node_tutor_service -->|"assess mastery"| node_diagnoser_service
node_tutor_service -->|"read/write memory"| node_student_db
node_planner_service -->|"traverse concepts"| node_graph_service
node_planner_service -->|"use history"| node_student_db
node_planner_service -->|"update state"| node_state_model
node_diagnoser_service -->|"generate checks"| node_llm_service
node_diagnoser_service -->|"record results"| node_diagnoses_model
node_tutor_service -->|"compose lessons"| node_tutor_utils
node_tutor_service -->|"track session"| node_state_model
node_concepts_json -->|"inspect"| node_notebook

click node_app "https://github.com/princ3kr/notebook-lm-mini/blob/main/app.py"
click node_pdf_service "https://github.com/princ3kr/notebook-lm-mini/blob/main/src/services/pdf_service.py"
click node_llm_service "https://github.com/princ3kr/notebook-lm-mini/blob/main/src/services/llm_service.py"
click node_concept_model "https://github.com/princ3kr/notebook-lm-mini/blob/main/src/models/concept.py"
click node_graph_service "https://github.com/princ3kr/notebook-lm-mini/blob/main/src/services/graph_service.py"
click node_neo4j_conn "https://github.com/princ3kr/notebook-lm-mini/blob/main/src/database/neo4j_conn.py"
click node_student_db "https://github.com/princ3kr/notebook-lm-mini/blob/main/src/database/student_db.py"
click node_intent_service "https://github.com/princ3kr/notebook-lm-mini/blob/main/src/services/intent_service.py"
click node_intent_model "https://github.com/princ3kr/notebook-lm-mini/blob/main/src/models/intent.py"
click node_planner_service "https://github.com/princ3kr/notebook-lm-mini/blob/main/src/services/planner_service.py"
click node_state_model "https://github.com/princ3kr/notebook-lm-mini/blob/main/src/models/state.py"
click node_diagnoser_service "https://github.com/princ3kr/notebook-lm-mini/blob/main/src/services/diagnoser_service.py"
click node_diagnoses_model "https://github.com/princ3kr/notebook-lm-mini/blob/main/src/models/diagnoses.py"
click node_tutor_service "https://github.com/princ3kr/notebook-lm-mini/blob/main/src/services/tutor_service.py"
click node_tutor_utils "https://github.com/princ3kr/notebook-lm-mini/blob/main/src/services/tutor_lesson_utils.py"
click node_concepts_json "https://github.com/princ3kr/notebook-lm-mini/blob/main/py-notebook/concepts.json"
click node_notebook "https://github.com/princ3kr/notebook-lm-mini/blob/main/py-notebook/testing.ipynb"

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_app toneBlue
class node_pdf_service,node_llm_service,node_graph_service toneAmber
class node_intent_service,node_planner_service,node_diagnoser_service,node_tutor_service,node_tutor_utils toneMint
class node_concept_model,node_neo4j_conn,node_student_db,node_intent_model,node_state_model,node_diagnoses_model toneRose
class node_concepts_json,node_notebook toneIndigo
```

## Components

### UI

Streamlit entrypoint and user-facing app

- [App](https://github.com/princ3kr/notebook-lm-mini/blob/main/app.py): streamlit entrypoint · Top-level UI and runtime entrypoint · `app.py`

### Ingestion

Document intake and knowledge-graph construction

- [PDF Intake](https://github.com/princ3kr/notebook-lm-mini/blob/main/src/services/pdf_service.py): document pipeline · Converts PDFs into clean text, chunks, and extractable units · `src/services/pdf_service.py`
- [LLM Gateway](https://github.com/princ3kr/notebook-lm-mini/blob/main/src/services/llm_service.py): model adapter · Centralized Groq prompt and response handling · `src/services/llm_service.py`
- [Graph Service](https://github.com/princ3kr/notebook-lm-mini/blob/main/src/services/graph_service.py): knowledge graph · Builds and queries concept relationships in Neo4j · `src/services/graph_service.py`

### Tutoring

Interactive planning, diagnosis, and lesson delivery

- [Intent Service](https://github.com/princ3kr/notebook-lm-mini/blob/main/src/services/intent_service.py): request parser · Interprets learner questions and goals · `src/services/intent_service.py`
- [Planner](https://github.com/princ3kr/notebook-lm-mini/blob/main/src/services/planner_service.py): learning path · Selects the next concepts and study sequence · `src/services/planner_service.py`
- [Diagnoser](https://github.com/princ3kr/notebook-lm-mini/blob/main/src/services/diagnoser_service.py): assessment loop · Evaluates understanding and drives diagnosis questions · `src/services/diagnoser_service.py`
- [Tutor Core](https://github.com/princ3kr/notebook-lm-mini/blob/main/src/services/tutor_service.py): orchestrator · Coordinates intent, planning, diagnosis, and teaching · `src/services/tutor_service.py`
- [Lesson Utils](https://github.com/princ3kr/notebook-lm-mini/blob/main/src/services/tutor_lesson_utils.py): support logic · Shared helpers for lesson composition and remediation · `src/services/tutor_lesson_utils.py`

### Data

Persistence and domain schemas

- [Concepts](https://github.com/princ3kr/notebook-lm-mini/blob/main/src/models/concept.py): domain schema · Structured concept representation for extracted knowledge · `src/models/concept.py`
- [Neo4j Conn](https://github.com/princ3kr/notebook-lm-mini/blob/main/src/database/neo4j_conn.py): db adapter · Connection and session boundary for Neo4j · `src/database/neo4j_conn.py`
- [Student DB](https://github.com/princ3kr/notebook-lm-mini/blob/main/src/database/student_db.py): session store · TinyDB-backed per-student history and mastery state · `src/database/student_db.py`
- [Intent](https://github.com/princ3kr/notebook-lm-mini/blob/main/src/models/intent.py): domain schema · Typed representation of parsed learner intent · `src/models/intent.py`
- [Session State](https://github.com/princ3kr/notebook-lm-mini/blob/main/src/models/state.py): domain schema · Current learner and tutor session state · `src/models/state.py`
- [Diagnoses](https://github.com/princ3kr/notebook-lm-mini/blob/main/src/models/diagnoses.py): domain schema · Typed assessment and diagnosis results · `src/models/diagnoses.py`

### Experiments

Notebook artifacts and extracted concept samples

- [Concept JSON](https://github.com/princ3kr/notebook-lm-mini/blob/main/py-notebook/concepts.json): sample data · Extracted concept artifacts used for inspection and experimentation · `py-notebook/concepts.json`
- [Notebook](https://github.com/princ3kr/notebook-lm-mini/blob/main/py-notebook/testing.ipynb): analysis notebook · Exploration and testing workspace for graph/content processing · `py-notebook/testing.ipynb`

## Connections

- App → PDF Intake: ingest content · UI can trigger document intake and processing
- App → Tutor Core: start tutoring · UI routes learner interaction into the tutoring loop
- PDF Intake → LLM Gateway: extract structure · Document chunks are turned into structured concepts via LLM calls
- LLM Gateway → Concepts: populate · LLM output is validated into concept schema
- Concepts → Graph Service: load graph · Validated concepts become graph ingestion input
- Graph Service → Neo4j Conn: persist/query · Graph operations are executed through the Neo4j adapter
- Intent Service → LLM Gateway: parse intent · Learner requests are interpreted with model assistance
- Intent Service → Intent: validate · Parsed requests are normalized into intent schema
- Tutor Core → Intent Service: understand request · Tutor first determines what the learner wants
- Tutor Core → Planner: plan path · Tutor delegates learning-path selection to planner
- Tutor Core → Diagnoser: assess mastery · Tutor invokes diagnosis during the teaching loop
- Tutor Core → Student DB: read/write memory · Tutor persists progress and retrieves session history
- Planner → Graph Service: traverse concepts · Planning depends on graph structure and relationships
- Planner → Student DB: use history · Planning adapts to prior performance and mastery
- Planner → Session State: update state · Planner refines session state as the path changes
- Diagnoser → LLM Gateway: generate checks · Diagnostic questions and reasoning can be LLM-assisted
- Diagnoser → Diagnoses: record results · Assessment outcomes are structured as diagnosis data
- Tutor Core → Lesson Utils: compose lessons · Shared lesson helpers support explanation and remediation
- Tutor Core → Session State: track session · Tutor maintains current interaction state
- Concept JSON → Notebook: inspect · Notebook explores extracted concept artifacts
