# 23at/cs360aitutor architecture

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

- Interactive diagram: https://gitdiagram.com/23at/cs360aitutor
- Repository: https://github.com/23at/cs360aitutor

## Overview

Cs360AItutor is a local-first AI course tutor for course materials, tutoring, quizzes, study planning, and progress tracking. Students use either the Streamlit interface or the command-line flow to work through courses; both route tutoring operations through AITutor, which coordinates document retrieval, persistence, and study planning. The graph also shows the separate progress-observer pattern and connector module. Some paths are supported only by the SOURCE INDEX or README, so unsampled behavior and uncertain wiring are omitted.

Main entry points: [`backend/ai_tutor.py`](https://github.com/23at/cs360aitutor/blob/asmi-streamlit/backend/ai_tutor.py) (Tutor coordinator), [`backend/file_facade.py`](https://github.com/23at/cs360aitutor/blob/asmi-streamlit/backend/file_facade.py) (Document and model facade), [`backend/study_planner.py`](https://github.com/23at/cs360aitutor/blob/asmi-streamlit/backend/study_planner.py) (Study planning), [`backend/database/tutor_db.py`](https://github.com/23at/cs360aitutor/blob/asmi-streamlit/backend/database/tutor_db.py) (Tutoring database)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Student interfaces"]
  node_streamlit["Streamlit app<br/>[app.py]"]
  node_cli["Command-line app<br/>[main.py]"]
end

subgraph group_learning["Learning workflows"]
  node_tutor["Tutor coordinator<br/>[ai_tutor.py]"]
  node_course_content["Course materials<br/>[ai_tutor.py]"]
  node_lessons_chat["Lessons and chat<br/>[ai_tutor.py]"]
  node_quizzes["Quiz workflows<br/>[ai_tutor.py]"]
  node_planner["Study planning<br/>[study_planner.py]"]
  node_connector["Connector workflows<br/>[connector_db.py]"]
end

subgraph group_ai_docs["AI and documents"]
  node_facade["Document and model facade<br/>[file_facade.py]"]
  node_vector["Vector retrieval<br/>[vector.py]"]
end

subgraph group_state["Progress and state"]
  node_database[("Tutoring database<br/>[tutor_db.py]")]
  node_progress_events["Progress observers<br/>[observers.py]"]
end

node_student(("Student"))
node_local_model{{"Local AI model"}}

node_student -->|"uses"| node_streamlit
node_student -->|"uses"| node_cli
node_streamlit -->|"calls"| node_tutor
node_cli -->|"calls"| node_tutor
node_tutor -->|"manages"| node_course_content
node_tutor -->|"handles"| node_lessons_chat
node_tutor -->|"generates"| node_quizzes
node_tutor -->|"delegates"| node_planner
node_tutor -->|"queries"| node_facade
node_tutor -->|"persists"| node_database
node_planner -->|"reads and writes"| node_database
node_planner -->|"queries"| node_facade
node_facade -->|"retrieves"| node_vector
node_facade -.->|"invokes"| node_local_model
node_connector -->|"persists"| node_database
node_connector -->|"uploads and queries"| node_facade
node_progress_events -->|"notifies observers"| node_progress_events

click node_streamlit "https://github.com/23at/cs360aitutor/blob/asmi-streamlit/app.py"
click node_cli "https://github.com/23at/cs360aitutor/blob/asmi-streamlit/backend/main.py"
click node_tutor "https://github.com/23at/cs360aitutor/blob/asmi-streamlit/backend/ai_tutor.py"
click node_course_content "https://github.com/23at/cs360aitutor/blob/asmi-streamlit/backend/ai_tutor.py"
click node_lessons_chat "https://github.com/23at/cs360aitutor/blob/asmi-streamlit/backend/ai_tutor.py"
click node_quizzes "https://github.com/23at/cs360aitutor/blob/asmi-streamlit/backend/ai_tutor.py"
click node_planner "https://github.com/23at/cs360aitutor/blob/asmi-streamlit/backend/study_planner.py"
click node_facade "https://github.com/23at/cs360aitutor/blob/asmi-streamlit/backend/file_facade.py"
click node_vector "https://github.com/23at/cs360aitutor/blob/asmi-streamlit/backend/vector.py"
click node_database "https://github.com/23at/cs360aitutor/blob/asmi-streamlit/backend/database/tutor_db.py"
click node_connector "https://github.com/23at/cs360aitutor/blob/asmi-streamlit/backend/connector_db.py"
click node_progress_events "https://github.com/23at/cs360aitutor/blob/asmi-streamlit/backend/observers.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_streamlit,node_cli toneBlue
class node_tutor,node_course_content,node_lessons_chat,node_quizzes,node_planner,node_connector toneAmber
class node_facade,node_vector toneMint
class node_database,node_progress_events toneRose
class node_student,node_local_model toneIndigo
```

## Components

### Student interfaces

- [Streamlit app](https://github.com/23at/cs360aitutor/blob/asmi-streamlit/app.py): `app.py`
- [Command-line app](https://github.com/23at/cs360aitutor/blob/asmi-streamlit/backend/main.py): `backend/main.py`

### Learning workflows

- [Tutor coordinator](https://github.com/23at/cs360aitutor/blob/asmi-streamlit/backend/ai_tutor.py): `backend/ai_tutor.py`
- [Course materials](https://github.com/23at/cs360aitutor/blob/asmi-streamlit/backend/ai_tutor.py): `backend/ai_tutor.py`
- [Lessons and chat](https://github.com/23at/cs360aitutor/blob/asmi-streamlit/backend/ai_tutor.py): `backend/ai_tutor.py`
- [Quiz workflows](https://github.com/23at/cs360aitutor/blob/asmi-streamlit/backend/ai_tutor.py): `backend/ai_tutor.py`
- [Study planning](https://github.com/23at/cs360aitutor/blob/asmi-streamlit/backend/study_planner.py): `backend/study_planner.py`
- [Connector workflows](https://github.com/23at/cs360aitutor/blob/asmi-streamlit/backend/connector_db.py): `backend/connector_db.py`

### AI and documents

- [Document and model facade](https://github.com/23at/cs360aitutor/blob/asmi-streamlit/backend/file_facade.py): `backend/file_facade.py`
- [Vector retrieval](https://github.com/23at/cs360aitutor/blob/asmi-streamlit/backend/vector.py): `backend/vector.py`

### Progress and state

- [Tutoring database](https://github.com/23at/cs360aitutor/blob/asmi-streamlit/backend/database/tutor_db.py): `backend/database/tutor_db.py`
- [Progress observers](https://github.com/23at/cs360aitutor/blob/asmi-streamlit/backend/observers.py): `backend/observers.py`

### Other components

- **Student**
- **Local AI model**

## Connections

- Student → Streamlit app: uses (evidence: `README.md`)
- Student → Command-line app: uses (evidence: `backend/main.py`)
- Streamlit app → Tutor coordinator: calls (evidence: `app.py`)
- Command-line app → Tutor coordinator: calls (evidence: `backend/main.py`)
- Tutor coordinator → Course materials: manages (evidence: `backend/ai_tutor.py`)
- Tutor coordinator → Lessons and chat: handles (evidence: `backend/ai_tutor.py`)
- Tutor coordinator → Quiz workflows: generates (evidence: `backend/ai_tutor.py`)
- Tutor coordinator → Study planning: delegates (evidence: `backend/ai_tutor.py`)
- Tutor coordinator → Document and model facade: queries (evidence: `backend/ai_tutor.py`)
- Tutor coordinator → Tutoring database: persists (evidence: `backend/ai_tutor.py`)
- Study planning → Tutoring database: reads and writes (evidence: `backend/study_planner.py`)
- Study planning → Document and model facade: queries (evidence: `backend/study_planner.py`)
- Document and model facade → Vector retrieval: retrieves (evidence: `backend/file_facade.py`)
- Document and model facade → Local AI model: invokes (evidence: `README.md`)
- Connector workflows → Tutoring database: persists (evidence: `backend/connector_db.py`)
- Connector workflows → Document and model facade: uploads and queries (evidence: `backend/connector_db.py`)
- Progress observers → Progress observers: notifies observers (evidence: `backend/observers.py`)
