# tokaelfawey/hcai_project architecture

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

- Interactive diagram: https://gitdiagram.com/tokaelfawey/hcai_project
- Repository: https://github.com/tokaelfawey/hcai_project

## Overview

The repository is an interactive academic-planning simulator: students set constraints, explore bounded course drafts, and retain control through actions such as locking, rejecting, undoing, and accepting proposals. A separate schedule-and-chat workflow supports schedule changes and uploaded-material workload analysis. The main app and core modules are excerpted; links to unsampled features are included only where the README or source index supports them.

Main entry points: [`Acdemic stimulor implemenation/academic_decision_simulator.py`](https://github.com/tokaelfawey/hcai_project/blob/main/Acdemic%20stimulor%20implemenation/academic_decision_simulator.py) (Decision Simulator), [`Acdemic stimulor implemenation/Dashboard.py`](https://github.com/tokaelfawey/hcai_project/blob/main/Acdemic%20stimulor%20implemenation/Dashboard.py) (Streamlit Dashboard), [`Acdemic stimulor implemenation/course_planner.py`](https://github.com/tokaelfawey/hcai_project/blob/main/Acdemic%20stimulor%20implemenation/course_planner.py) (Course Planner), [`Acdemic stimulor implemenation/gemini_llm.py`](https://github.com/tokaelfawey/hcai_project/blob/main/Acdemic%20stimulor%20implemenation/gemini_llm.py) (Gemini Adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Student Interface"]
  node_dashboard["Streamlit Dashboard<br/>[Dashboard.py]"]
  node_theme["Accessible Themes<br/>[project_theme.py]"]
end

subgraph group_planning["Course Planning"]
  node_planner["Course Planner<br/>[course_planner.py]"]
  node_catalog["Course Catalog<br/>[course_catalog.csv]"]
  node_drafts["Course Drafts<br/>[course_planner.py]"]
end

subgraph group_simulation["Schedule Simulation"]
  node_simulator["Decision Simulator"]
  node_llm["Gemini Adapter<br/>[gemini_llm.py]"]
  node_schedule[("Schedule State")]
  node_chat[("Chat History")]
  node_proposals["Schedule Proposals"]
end

subgraph group_knowledge["Material Analysis"]
  node_analyzer["Document Workload Analyzer"]
  node_chroma[("Material Vectors")]
end

node_student(("Student"))
node_gemini{{"Gemini API"}}
node_uploaded["Course Materials"]

node_student -->|"uses"| node_dashboard
node_dashboard -->|"creates"| node_simulator
node_dashboard -->|"applies"| node_theme
node_dashboard -->|"initializes"| node_llm
node_simulator -->|"delegates planning"| node_planner
node_planner -->|"loads courses"| node_catalog
node_planner -.->|"generates"| node_drafts
node_simulator -.->|"uses analysis"| node_analyzer
node_student -.->|"provides"| node_uploaded
node_analyzer -->|"stores vectors"| node_chroma
node_simulator -->|"persists schedule"| node_schedule
node_simulator -.->|"persists chat"| node_chat
node_simulator -->|"prepares changes"| node_proposals
node_llm -->|"requests completion"| node_gemini
node_simulator -.->|"requests response"| node_llm

click node_dashboard "https://github.com/tokaelfawey/hcai_project/blob/main/Acdemic%20stimulor%20implemenation/Dashboard.py"
click node_theme "https://github.com/tokaelfawey/hcai_project/blob/main/Acdemic%20stimulor%20implemenation/project_theme.py"
click node_simulator "https://github.com/tokaelfawey/hcai_project/blob/main/Acdemic%20stimulor%20implemenation/academic_decision_simulator.py"
click node_planner "https://github.com/tokaelfawey/hcai_project/blob/main/Acdemic%20stimulor%20implemenation/course_planner.py"
click node_catalog "https://github.com/tokaelfawey/hcai_project/blob/main/Acdemic%20stimulor%20implemenation/data/course_catalog.csv"
click node_llm "https://github.com/tokaelfawey/hcai_project/blob/main/Acdemic%20stimulor%20implemenation/gemini_llm.py"
click node_schedule "https://github.com/tokaelfawey/hcai_project/blob/main/Acdemic%20stimulor%20implemenation/data/academic_simulator_schedule.json"
click node_chat "https://github.com/tokaelfawey/hcai_project/blob/main/Acdemic%20stimulor%20implemenation/data/academic_simulator_chat.json"
click node_analyzer "https://github.com/tokaelfawey/hcai_project/blob/main/Acdemic%20stimulor%20implemenation/document_workload_analyzer.py"
click node_chroma "https://github.com/tokaelfawey/hcai_project/tree/main/Acdemic%20stimulor%20implemenation/data/course_material_chroma"
click node_proposals "https://github.com/tokaelfawey/hcai_project/blob/main/Acdemic%20stimulor%20implemenation/academic_decision_simulator.py"
click node_drafts "https://github.com/tokaelfawey/hcai_project/blob/main/Acdemic%20stimulor%20implemenation/course_planner.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_dashboard,node_theme toneBlue
class node_planner,node_catalog,node_drafts toneAmber
class node_simulator,node_llm,node_schedule,node_chat,node_proposals,node_gemini toneMint
class node_analyzer,node_chroma toneRose
class node_student,node_uploaded toneIndigo
```

## Components

### Student Interface

- [Streamlit Dashboard](https://github.com/tokaelfawey/hcai_project/blob/main/Acdemic%20stimulor%20implemenation/Dashboard.py): `Acdemic stimulor implemenation/Dashboard.py`
- [Accessible Themes](https://github.com/tokaelfawey/hcai_project/blob/main/Acdemic%20stimulor%20implemenation/project_theme.py): `Acdemic stimulor implemenation/project_theme.py`

### Course Planning

- [Course Planner](https://github.com/tokaelfawey/hcai_project/blob/main/Acdemic%20stimulor%20implemenation/course_planner.py): `Acdemic stimulor implemenation/course_planner.py`
- [Course Catalog](https://github.com/tokaelfawey/hcai_project/blob/main/Acdemic%20stimulor%20implemenation/data/course_catalog.csv): `Acdemic stimulor implemenation/data/course_catalog.csv`
- [Course Drafts](https://github.com/tokaelfawey/hcai_project/blob/main/Acdemic%20stimulor%20implemenation/course_planner.py): `Acdemic stimulor implemenation/course_planner.py`

### Schedule Simulation

- [Decision Simulator](https://github.com/tokaelfawey/hcai_project/blob/main/Acdemic%20stimulor%20implemenation/academic_decision_simulator.py): `Acdemic stimulor implemenation/academic_decision_simulator.py`
- [Gemini Adapter](https://github.com/tokaelfawey/hcai_project/blob/main/Acdemic%20stimulor%20implemenation/gemini_llm.py): `Acdemic stimulor implemenation/gemini_llm.py`
- [Schedule State](https://github.com/tokaelfawey/hcai_project/blob/main/Acdemic%20stimulor%20implemenation/data/academic_simulator_schedule.json): `Acdemic stimulor implemenation/data/academic_simulator_schedule.json`
- [Chat History](https://github.com/tokaelfawey/hcai_project/blob/main/Acdemic%20stimulor%20implemenation/data/academic_simulator_chat.json): `Acdemic stimulor implemenation/data/academic_simulator_chat.json`
- [Schedule Proposals](https://github.com/tokaelfawey/hcai_project/blob/main/Acdemic%20stimulor%20implemenation/academic_decision_simulator.py): `Acdemic stimulor implemenation/academic_decision_simulator.py`

### Material Analysis

- [Document Workload Analyzer](https://github.com/tokaelfawey/hcai_project/blob/main/Acdemic%20stimulor%20implemenation/document_workload_analyzer.py): `Acdemic stimulor implemenation/document_workload_analyzer.py`
- [Material Vectors](https://github.com/tokaelfawey/hcai_project/tree/main/Acdemic%20stimulor%20implemenation/data/course_material_chroma): `Acdemic stimulor implemenation/data/course_material_chroma`

### Other components

- **Student**
- **Gemini API**
- **Course Materials**

## Connections

- Student → Streamlit Dashboard: uses (evidence: `README.md`)
- Streamlit Dashboard → Decision Simulator: creates (evidence: `Acdemic stimulor implemenation/Dashboard.py`)
- Streamlit Dashboard → Accessible Themes: applies (evidence: `Acdemic stimulor implemenation/Dashboard.py`)
- Streamlit Dashboard → Gemini Adapter: initializes (evidence: `Acdemic stimulor implemenation/Dashboard.py`)
- Decision Simulator → Course Planner: delegates planning (evidence: `Acdemic stimulor implemenation/academic_decision_simulator.py`)
- Course Planner → Course Catalog: loads courses (evidence: `Acdemic stimulor implemenation/course_planner.py`)
- Course Planner → Course Drafts: generates (evidence: `README.md`)
- Decision Simulator → Document Workload Analyzer: uses analysis (evidence: `Acdemic stimulor implemenation/academic_decision_simulator.py`)
- Student → Course Materials: provides (evidence: `README.md`)
- Document Workload Analyzer → Material Vectors: stores vectors (evidence: `Acdemic stimulor implemenation/document_workload_analyzer.py`)
- Decision Simulator → Schedule State: persists schedule (evidence: `Acdemic stimulor implemenation/academic_decision_simulator.py`)
- Decision Simulator → Chat History: persists chat
- Decision Simulator → Schedule Proposals: prepares changes (evidence: `Acdemic stimulor implemenation/academic_decision_simulator.py`)
- Gemini Adapter → Gemini API: requests completion (evidence: `Acdemic stimulor implemenation/gemini_llm.py`)
- Decision Simulator → Gemini Adapter: requests response
