# govindasaikiran/helix architecture

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

- Interactive diagram: https://gitdiagram.com/govindasaikiran/helix
- Repository: https://github.com/govindasaikiran/helix

## Overview

HELIX is an adaptive student planner and study platform. Students provide academic work, deadlines, syllabus material, and availability through the app; planning and AI features turn that input into proposed schedules and study materials, while deterministic planning supports schedule repair. The app also provides timetable, project, quiz, analytics, timer, and notification features. The README documents these capabilities, but several feature implementations and their wiring are not included in the sampled source, so those links are left broad or omitted.

Main entry points: [`src/App.tsx`](https://github.com/govindasaikiran/helix/blob/main/src/App.tsx) (App Router), [`src/services/aiService.ts`](https://github.com/govindasaikiran/helix/blob/main/src/services/aiService.ts) (AI Service), [`src/pages/TopicLearningPage.tsx`](https://github.com/govindasaikiran/helix/blob/main/src/pages/TopicLearningPage.tsx) (Topic Learning), [`src/pages`](https://github.com/govindasaikiran/helix/tree/main/src/pages) (Planner Pages)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Student App"]
  node_app["App Router<br/>[App.tsx]"]
  node_auth["Authentication<br/>[AuthContext.tsx]"]
  node_corepages["Planner Pages"]
  node_timer["Study Timers"]
end

subgraph group_planning["Planning and Agent"]
  node_agentpage["Planning Agent Page"]
  node_chatbot["Agent Chat UI<br/>[AgentChatbot.tsx]"]
  node_ai["AI Service<br/>[aiService.ts]"]
  node_intent["Intent Router<br/>[intentRouter.ts]"]
  node_executor["Agent Executor<br/>[agentExecutor.ts]"]
  node_planner["Planner Service<br/>[plannerService.ts]"]
  node_detplanner["Deterministic Planner"]
end

subgraph group_study["Study Intelligence"]
  node_studyhub["Study Hub<br/>[StudyHubPage.tsx]"]
  node_learning["Topic Learning"]
  node_quiz["Quiz Practice<br/>[QuizPage.tsx]"]
  node_pdf["PDF Text Extraction<br/>[pdfParser.ts]"]
end

subgraph group_data["Academic Data"]
  node_data_services["Academic Services<br/>[taskService.ts]"]
  node_planstate["Plan State<br/>[PlanContext.tsx]"]
  node_supabaseclient["Supabase Client<br/>[supabaseClient.ts]"]
end

subgraph group_integrations["External Services"]
  node_supabase[("Supabase")]
  node_server["API Server<br/>[index.ts]"]
  node_aiapi["AI API Route<br/>[generate.ts]"]
  node_gemini{{"Gemini AI"}}
  node_youtube["YouTube Search<br/>[search.ts]"]
  node_youtube_api{{"YouTube API"}}
  node_notifications["Notification Services"]
  node_firebase["Firebase Messaging"]
  node_fcm{{"Firebase Cloud Messaging"}}
end

node_student(("Student"))

node_student -->|"uses"| node_app
node_app -->|"provides auth"| node_auth
node_app -->|"routes to"| node_corepages
node_app -->|"provides plan state"| node_planstate
node_corepages -.->|"offers timer"| node_timer
node_student -->|"requests plans"| node_chatbot
node_chatbot -->|"opens"| node_agentpage
node_agentpage -.->|"requests agent work"| node_ai
node_ai -->|"executes agent"| node_executor
node_executor -->|"classifies input"| node_intent
node_student -->|"studies"| node_studyhub
node_studyhub -->|"opens topics"| node_learning
node_learning -->|"practices"| node_quiz
node_learning -.->|"extracts material"| node_pdf
node_ai -.->|"requests generation"| node_aiapi
node_aiapi -.->|"generates content"| node_gemini
node_student -->|"submits workload"| node_planner
node_planner -.->|"requests schedule logic"| node_detplanner
node_server -->|"builds replan proposal"| node_detplanner
node_planstate -.->|"uses academic data"| node_data_services
node_data_services -->|"reads and writes"| node_supabaseclient
node_supabaseclient -->|"queries"| node_supabase
node_student -.->|"requests lectures"| node_youtube
node_youtube -->|"searches videos"| node_youtube_api
node_notifications -.->|"uses messaging"| node_firebase
node_firebase -->|"sends push"| node_fcm

click node_app "https://github.com/govindasaikiran/helix/blob/main/src/App.tsx"
click node_auth "https://github.com/govindasaikiran/helix/blob/main/src/context/AuthContext.tsx"
click node_corepages "https://github.com/govindasaikiran/helix/tree/main/src/pages"
click node_timer "https://github.com/govindasaikiran/helix/blob/main/src/components/shared/FloatingStudyTimer.tsx"
click node_agentpage "https://github.com/govindasaikiran/helix/blob/main/src/pages/PlanningAgentPage.tsx"
click node_chatbot "https://github.com/govindasaikiran/helix/blob/main/src/components/shared/AgentChatbot.tsx"
click node_ai "https://github.com/govindasaikiran/helix/blob/main/src/services/aiService.ts"
click node_intent "https://github.com/govindasaikiran/helix/blob/main/src/services/agent/intentRouter.ts"
click node_executor "https://github.com/govindasaikiran/helix/blob/main/src/services/agent/agentExecutor.ts"
click node_planner "https://github.com/govindasaikiran/helix/blob/main/src/services/plannerService.ts"
click node_detplanner "https://github.com/govindasaikiran/helix/blob/main/server/planner/deterministicPlanner.ts"
click node_studyhub "https://github.com/govindasaikiran/helix/blob/main/src/pages/StudyHubPage.tsx"
click node_learning "https://github.com/govindasaikiran/helix/blob/main/src/pages/TopicLearningPage.tsx"
click node_quiz "https://github.com/govindasaikiran/helix/blob/main/src/pages/QuizPage.tsx"
click node_pdf "https://github.com/govindasaikiran/helix/blob/main/src/utils/pdfParser.ts"
click node_data_services "https://github.com/govindasaikiran/helix/blob/main/src/services/taskService.ts"
click node_planstate "https://github.com/govindasaikiran/helix/blob/main/src/context/PlanContext.tsx"
click node_supabaseclient "https://github.com/govindasaikiran/helix/blob/main/src/lib/supabaseClient.ts"
click node_server "https://github.com/govindasaikiran/helix/blob/main/server/index.ts"
click node_aiapi "https://github.com/govindasaikiran/helix/blob/main/api/ai/generate.ts"
click node_youtube "https://github.com/govindasaikiran/helix/blob/main/api/youtube/search.ts"
click node_notifications "https://github.com/govindasaikiran/helix/blob/main/src/services/notificationService.ts"
click node_firebase "https://github.com/govindasaikiran/helix/blob/main/src/services/firebaseMessaging.ts"

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_auth,node_corepages,node_timer toneBlue
class node_agentpage,node_chatbot,node_ai,node_intent,node_executor,node_planner,node_detplanner toneAmber
class node_studyhub,node_learning,node_quiz,node_pdf toneMint
class node_data_services,node_planstate,node_supabaseclient toneRose
class node_supabase,node_server,node_aiapi,node_gemini,node_youtube,node_youtube_api,node_notifications,node_firebase,node_fcm,node_student toneIndigo
```

## Components

### Student App

- [App Router](https://github.com/govindasaikiran/helix/blob/main/src/App.tsx): `src/App.tsx`
- [Authentication](https://github.com/govindasaikiran/helix/blob/main/src/context/AuthContext.tsx): `src/context/AuthContext.tsx`
- [Planner Pages](https://github.com/govindasaikiran/helix/tree/main/src/pages): `src/pages`
- [Study Timers](https://github.com/govindasaikiran/helix/blob/main/src/components/shared/FloatingStudyTimer.tsx): `src/components/shared/FloatingStudyTimer.tsx`

### Planning and Agent

- [Planning Agent Page](https://github.com/govindasaikiran/helix/blob/main/src/pages/PlanningAgentPage.tsx): `src/pages/PlanningAgentPage.tsx`
- [Agent Chat UI](https://github.com/govindasaikiran/helix/blob/main/src/components/shared/AgentChatbot.tsx): `src/components/shared/AgentChatbot.tsx`
- [AI Service](https://github.com/govindasaikiran/helix/blob/main/src/services/aiService.ts): `src/services/aiService.ts`
- [Intent Router](https://github.com/govindasaikiran/helix/blob/main/src/services/agent/intentRouter.ts): `src/services/agent/intentRouter.ts`
- [Agent Executor](https://github.com/govindasaikiran/helix/blob/main/src/services/agent/agentExecutor.ts): `src/services/agent/agentExecutor.ts`
- [Planner Service](https://github.com/govindasaikiran/helix/blob/main/src/services/plannerService.ts): `src/services/plannerService.ts`
- [Deterministic Planner](https://github.com/govindasaikiran/helix/blob/main/server/planner/deterministicPlanner.ts): `server/planner/deterministicPlanner.ts`

### Study Intelligence

- [Study Hub](https://github.com/govindasaikiran/helix/blob/main/src/pages/StudyHubPage.tsx): `src/pages/StudyHubPage.tsx`
- [Topic Learning](https://github.com/govindasaikiran/helix/blob/main/src/pages/TopicLearningPage.tsx): `src/pages/TopicLearningPage.tsx`
- [Quiz Practice](https://github.com/govindasaikiran/helix/blob/main/src/pages/QuizPage.tsx): `src/pages/QuizPage.tsx`
- [PDF Text Extraction](https://github.com/govindasaikiran/helix/blob/main/src/utils/pdfParser.ts): `src/utils/pdfParser.ts`

### Academic Data

- [Academic Services](https://github.com/govindasaikiran/helix/blob/main/src/services/taskService.ts): `src/services/taskService.ts`
- [Plan State](https://github.com/govindasaikiran/helix/blob/main/src/context/PlanContext.tsx): `src/context/PlanContext.tsx`
- [Supabase Client](https://github.com/govindasaikiran/helix/blob/main/src/lib/supabaseClient.ts): `src/lib/supabaseClient.ts`

### External Services

- **Supabase**
- [API Server](https://github.com/govindasaikiran/helix/blob/main/server/index.ts): `server/index.ts`
- [AI API Route](https://github.com/govindasaikiran/helix/blob/main/api/ai/generate.ts): `api/ai/generate.ts`
- **Gemini AI**
- [YouTube Search](https://github.com/govindasaikiran/helix/blob/main/api/youtube/search.ts): `api/youtube/search.ts`
- **YouTube API**
- [Notification Services](https://github.com/govindasaikiran/helix/blob/main/src/services/notificationService.ts): `src/services/notificationService.ts`
- [Firebase Messaging](https://github.com/govindasaikiran/helix/blob/main/src/services/firebaseMessaging.ts): `src/services/firebaseMessaging.ts`
- **Firebase Cloud Messaging**

### Other components

- **Student**

## Connections

- Student → App Router: uses
- App Router → Authentication: provides auth
- App Router → Planner Pages: routes to
- App Router → Plan State: provides plan state
- Planner Pages → Study Timers: offers timer
- Student → Agent Chat UI: requests plans
- Agent Chat UI → Planning Agent Page: opens
- Planning Agent Page → AI Service: requests agent work
- AI Service → Agent Executor: executes agent
- Agent Executor → Intent Router: classifies input
- Student → Study Hub: studies
- Study Hub → Topic Learning: opens topics
- Topic Learning → Quiz Practice: practices
- Topic Learning → PDF Text Extraction: extracts material
- AI Service → AI API Route: requests generation
- AI API Route → Gemini AI: generates content
- Student → Planner Service: submits workload
- Planner Service → Deterministic Planner: requests schedule logic
- API Server → Deterministic Planner: builds replan proposal
- Plan State → Academic Services: uses academic data
- Academic Services → Supabase Client: reads and writes
- Supabase Client → Supabase: queries
- Student → YouTube Search: requests lectures
- YouTube Search → YouTube API: searches videos
- Notification Services → Firebase Messaging: uses messaging
- Firebase Messaging → Firebase Cloud Messaging: sends push