# govindjs5805/helen-ai architecture

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

- Interactive diagram: https://gitdiagram.com/govindjs5805/helen-ai
- Repository: https://github.com/govindjs5805/helen-ai

## Overview

Helen AI is an adaptive learning platform for students and teachers. A representative workflow is: a learner submits material in the document simplifier, the FastAPI backend extracts text (using OCR when needed), generates adapted outputs with AI, and saves or retrieves results. The React app also provides authentication and onboarding, personalized accessibility settings, tutoring, focus and planning tools, and teacher classroom/progress views. Backend internals and several frontend pages were not excerpted; the broader feature branches and their connections below rely on README documentation rather than inspection of those implementations.

Main entry points: [`helen-ai/backend/main.py`](https://github.com/govindjs5805/helen-ai/blob/main/helen-ai/backend/main.py) (FastAPI endpoints), [`helen-ai/src/App.tsx`](https://github.com/govindjs5805/helen-ai/blob/main/helen-ai/src/App.tsx) (React application), [`helen-ai/src/pages/student/DocumentSimplifier.tsx`](https://github.com/govindjs5805/helen-ai/blob/main/helen-ai/src/pages/student/DocumentSimplifier.tsx) (Document simplifier), [`helen-ai/src/services/api.ts`](https://github.com/govindjs5805/helen-ai/blob/main/helen-ai/src/services/api.ts) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Learning experience"]
  node_app["React application<br/>[App.tsx]"]
  node_authui["Sign-in and onboarding<br/>[Auth.tsx]"]
  node_authctx["Session and profile<br/>[AuthContext.tsx]"]
  node_supabaseauth["Supabase Auth"]
  node_docs["Document simplifier"]
  node_assistant["AI learning assistant<br/>[AIAssistant.tsx]"]
  node_api["API client<br/>[api.ts]"]
end

subgraph group_accessibility["Accessibility and profiles"]
  node_accessui["Accessibility settings"]
  node_reading["Reading preferences"]
  node_themes["Theme preferences<br/>[ThemeContext.tsx]"]
end

subgraph group_study["Study support"]
  node_focus["Focus and planner<br/>[FocusMode.tsx]"]
  node_attention["Attention sharing<br/>[attentionApi.ts]"]
end

subgraph group_backend["Backend processing"]
  node_backendapi["FastAPI endpoints<br/>[main.py]"]
  node_extract["Document extraction<br/>[main.py]"]
  node_ocr["OCR processing<br/>[main.py]"]
  node_ai["Gemini AI"]
  node_storage[("Supabase database")]
end

subgraph group_classroom["Classroom tools"]
  node_classrooms["Classroom management<br/>[Classrooms.tsx]"]
  node_progress["Student progress"]
  node_teacher["Teacher dashboard<br/>[Dashboard.tsx]"]
end

node_learner(("Student / teacher"))

node_learner -->|"uses"| node_app
node_app -->|"routes to"| node_authui
node_authui -->|"authenticates through"| node_authctx
node_authctx -->|"manages session"| node_supabaseauth
node_app -->|"routes to"| node_docs
node_docs -->|"submits material"| node_api
node_api -->|"sends requests"| node_backendapi
node_backendapi -->|"validates token"| node_supabaseauth
node_backendapi -->|"extracts content"| node_extract
node_extract -->|"uses when needed"| node_ocr
node_backendapi -->|"generates adapted output"| node_ai
node_backendapi -->|"saves results"| node_storage
node_backendapi -->|"returns results"| node_docs
node_assistant -.->|"requests tutoring"| node_api
node_accessui -.->|"updates preferences"| node_reading
node_reading -.->|"persists preferences"| node_storage
node_learner -->|"uses study tools"| node_focus
node_focus -.->|"shares summaries"| node_attention
node_learner -->|"uses classroom tools"| node_classrooms
node_teacher -->|"views progress"| node_progress
node_teacher -->|"manages classes"| node_classrooms
node_themes -.->|"persists settings"| node_storage

click node_app "https://github.com/govindjs5805/helen-ai/blob/main/helen-ai/src/App.tsx"
click node_authui "https://github.com/govindjs5805/helen-ai/blob/main/helen-ai/src/pages/Auth.tsx"
click node_authctx "https://github.com/govindjs5805/helen-ai/blob/main/helen-ai/src/context/AuthContext.tsx"
click node_docs "https://github.com/govindjs5805/helen-ai/blob/main/helen-ai/src/pages/student/DocumentSimplifier.tsx"
click node_assistant "https://github.com/govindjs5805/helen-ai/blob/main/helen-ai/src/pages/AIAssistant.tsx"
click node_api "https://github.com/govindjs5805/helen-ai/blob/main/helen-ai/src/services/api.ts"
click node_accessui "https://github.com/govindjs5805/helen-ai/blob/main/helen-ai/src/pages/ReadingSettings.tsx"
click node_reading "https://github.com/govindjs5805/helen-ai/blob/main/helen-ai/src/context/ReadingThemeContext.tsx"
click node_themes "https://github.com/govindjs5805/helen-ai/blob/main/helen-ai/src/context/ThemeContext.tsx"
click node_focus "https://github.com/govindjs5805/helen-ai/blob/main/helen-ai/src/pages/FocusMode.tsx"
click node_attention "https://github.com/govindjs5805/helen-ai/blob/main/helen-ai/src/services/attentionApi.ts"
click node_backendapi "https://github.com/govindjs5805/helen-ai/blob/main/helen-ai/backend/main.py"
click node_extract "https://github.com/govindjs5805/helen-ai/blob/main/helen-ai/backend/main.py"
click node_ocr "https://github.com/govindjs5805/helen-ai/blob/main/helen-ai/backend/main.py"
click node_classrooms "https://github.com/govindjs5805/helen-ai/blob/main/helen-ai/src/pages/Classrooms.tsx"
click node_progress "https://github.com/govindjs5805/helen-ai/blob/main/helen-ai/src/pages/teacher/StudentProgress.tsx"
click node_teacher "https://github.com/govindjs5805/helen-ai/blob/main/helen-ai/src/pages/teacher/Dashboard.tsx"

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,node_authui,node_authctx,node_supabaseauth,node_docs,node_assistant,node_api toneBlue
class node_accessui,node_reading,node_themes toneAmber
class node_focus,node_attention toneMint
class node_backendapi,node_extract,node_ocr,node_ai,node_storage toneRose
class node_classrooms,node_progress,node_teacher,node_learner toneIndigo
```

## Components

### Learning experience

- [React application](https://github.com/govindjs5805/helen-ai/blob/main/helen-ai/src/App.tsx): `helen-ai/src/App.tsx`
- [Sign-in and onboarding](https://github.com/govindjs5805/helen-ai/blob/main/helen-ai/src/pages/Auth.tsx): `helen-ai/src/pages/Auth.tsx`
- [Session and profile](https://github.com/govindjs5805/helen-ai/blob/main/helen-ai/src/context/AuthContext.tsx): `helen-ai/src/context/AuthContext.tsx`
- **Supabase Auth**
- [Document simplifier](https://github.com/govindjs5805/helen-ai/blob/main/helen-ai/src/pages/student/DocumentSimplifier.tsx): `helen-ai/src/pages/student/DocumentSimplifier.tsx`
- [AI learning assistant](https://github.com/govindjs5805/helen-ai/blob/main/helen-ai/src/pages/AIAssistant.tsx): `helen-ai/src/pages/AIAssistant.tsx`
- [API client](https://github.com/govindjs5805/helen-ai/blob/main/helen-ai/src/services/api.ts): `helen-ai/src/services/api.ts`

### Accessibility and profiles

- [Accessibility settings](https://github.com/govindjs5805/helen-ai/blob/main/helen-ai/src/pages/ReadingSettings.tsx): `helen-ai/src/pages/ReadingSettings.tsx`
- [Reading preferences](https://github.com/govindjs5805/helen-ai/blob/main/helen-ai/src/context/ReadingThemeContext.tsx): `helen-ai/src/context/ReadingThemeContext.tsx`
- [Theme preferences](https://github.com/govindjs5805/helen-ai/blob/main/helen-ai/src/context/ThemeContext.tsx): `helen-ai/src/context/ThemeContext.tsx`

### Study support

- [Focus and planner](https://github.com/govindjs5805/helen-ai/blob/main/helen-ai/src/pages/FocusMode.tsx): `helen-ai/src/pages/FocusMode.tsx`
- [Attention sharing](https://github.com/govindjs5805/helen-ai/blob/main/helen-ai/src/services/attentionApi.ts): `helen-ai/src/services/attentionApi.ts`

### Backend processing

- [FastAPI endpoints](https://github.com/govindjs5805/helen-ai/blob/main/helen-ai/backend/main.py): `helen-ai/backend/main.py`
- [Document extraction](https://github.com/govindjs5805/helen-ai/blob/main/helen-ai/backend/main.py): `helen-ai/backend/main.py`
- [OCR processing](https://github.com/govindjs5805/helen-ai/blob/main/helen-ai/backend/main.py): `helen-ai/backend/main.py`
- **Gemini AI**
- **Supabase database**

### Classroom tools

- [Classroom management](https://github.com/govindjs5805/helen-ai/blob/main/helen-ai/src/pages/Classrooms.tsx): `helen-ai/src/pages/Classrooms.tsx`
- [Student progress](https://github.com/govindjs5805/helen-ai/blob/main/helen-ai/src/pages/teacher/StudentProgress.tsx): `helen-ai/src/pages/teacher/StudentProgress.tsx`
- [Teacher dashboard](https://github.com/govindjs5805/helen-ai/blob/main/helen-ai/src/pages/teacher/Dashboard.tsx): `helen-ai/src/pages/teacher/Dashboard.tsx`

### Other components

- **Student / teacher**

## Connections

- Student / teacher → React application: uses (evidence: `README.md`)
- React application → Sign-in and onboarding: routes to (evidence: `helen-ai/src/App.tsx`)
- Sign-in and onboarding → Session and profile: authenticates through (evidence: `README.md`)
- Session and profile → Supabase Auth: manages session (evidence: `README.md`)
- React application → Document simplifier: routes to (evidence: `helen-ai/src/App.tsx`)
- Document simplifier → API client: submits material (evidence: `README.md`)
- API client → FastAPI endpoints: sends requests (evidence: `README.md`)
- FastAPI endpoints → Supabase Auth: validates token (evidence: `README.md`)
- FastAPI endpoints → Document extraction: extracts content (evidence: `README.md`)
- Document extraction → OCR processing: uses when needed (evidence: `README.md`)
- FastAPI endpoints → Gemini AI: generates adapted output (evidence: `README.md`)
- FastAPI endpoints → Supabase database: saves results (evidence: `README.md`)
- FastAPI endpoints → Document simplifier: returns results (evidence: `README.md`)
- AI learning assistant → API client: requests tutoring
- Accessibility settings → Reading preferences: updates preferences
- Reading preferences → Supabase database: persists preferences
- Student / teacher → Focus and planner: uses study tools (evidence: `README.md`)
- Focus and planner → Attention sharing: shares summaries
- Student / teacher → Classroom management: uses classroom tools (evidence: `README.md`)
- Teacher dashboard → Student progress: views progress (evidence: `README.md`)
- Teacher dashboard → Classroom management: manages classes (evidence: `README.md`)
- Theme preferences → Supabase database: persists settings
