# lycan-xx/studywise-ai architecture

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

- Interactive diagram: https://gitdiagram.com/lycan-xx/studywise-ai
- Repository: https://github.com/lycan-xx/studywise-ai

## Overview

StudyWise AI turns user-provided material into courses and practice tests, then returns graded results, AI insights, and learning analytics. The main flow runs from the authenticated client through API routes to course/test controllers, AI generation, and Supabase storage; result and analytics endpoints expose the saved outcomes. The README also describes multi-provider failover, source-linked questions, preferences, and progress tracking. Some client-to-API and unsampled feature wiring is documented only at a high level, so those links are marked unverified or omitted.

Main entry points: [`client/src/App.tsx`](https://github.com/lycan-xx/studywise-ai/blob/main/client/src/App.tsx) (App routing), [`server/routes.ts`](https://github.com/lycan-xx/studywise-ai/blob/main/server/routes.ts) (API routing), [`client/src/services/apiService.ts`](https://github.com/lycan-xx/studywise-ai/blob/main/client/src/services/apiService.ts) (API client), [`server/services/AIService.ts`](https://github.com/lycan-xx/studywise-ai/blob/main/server/services/AIService.ts) (AI provider engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Study client"]
  node_app["App routing<br/>[App.tsx]"]
  node_courseui["Course study<br/>[ModuleContent.tsx]"]
  node_dashboard["Course creation<br/>[dashboard.tsx]"]
  node_testui["Test taking<br/>[module-test.tsx]"]
  node_summaryui["Results views<br/>[test-summary.tsx]"]
  node_clientapi["API client<br/>[apiService.ts]"]
  node_sourceproc["Document processing"]
  node_auth["Authentication<br/>[AuthContext.tsx]"]
end

subgraph group_api["Learning API"]
  node_routes["API routing<br/>[routes.ts]"]
  node_course["Course generation"]
  node_moduletest["Module tests"]
  node_testctrl["Test operations<br/>[TestController.ts]"]
  node_results["Results analytics"]
end

subgraph group_ai["AI generation"]
  node_aiengine["AI provider engine<br/>[AIService.ts]"]
end

subgraph group_data["Persistence and insights"]
  node_supabaseclient["Supabase access<br/>[supabase.ts]"]
  node_database[("Supabase database")]
end

node_learner(("Learner"))
node_provider{{"AI providers"}}

node_learner -->|"uses"| node_app
node_app -->|"routes to"| node_courseui
node_app -->|"routes to"| node_dashboard
node_app -->|"routes to"| node_testui
node_app -->|"routes to"| node_summaryui
node_app -->|"provides"| node_auth
node_dashboard -.->|"processes material"| node_sourceproc
node_dashboard -.->|"requests generation"| node_clientapi
node_courseui -.->|"requests course data"| node_clientapi
node_testui -.->|"submits answers"| node_clientapi
node_summaryui -.->|"requests results"| node_clientapi
node_clientapi -.->|"calls API"| node_routes
node_routes -->|"dispatches"| node_course
node_routes -->|"dispatches"| node_moduletest
node_routes -->|"dispatches"| node_testctrl
node_routes -->|"dispatches"| node_results
node_course -->|"generates course content"| node_aiengine
node_course -->|"stores course"| node_supabaseclient
node_moduletest -->|"generates questions"| node_aiengine
node_moduletest -->|"reads and writes tests"| node_supabaseclient
node_testctrl -->|"generates questions"| node_aiengine
node_results -->|"reads performance"| node_supabaseclient
node_aiengine -.->|"sends prompts"| node_provider
node_supabaseclient -->|"queries and persists"| node_database

click node_app "https://github.com/lycan-xx/studywise-ai/blob/main/client/src/App.tsx"
click node_courseui "https://github.com/lycan-xx/studywise-ai/blob/main/client/src/components/course/ModuleContent.tsx"
click node_dashboard "https://github.com/lycan-xx/studywise-ai/blob/main/client/src/pages/dashboard.tsx"
click node_testui "https://github.com/lycan-xx/studywise-ai/blob/main/client/src/pages/module-test.tsx"
click node_summaryui "https://github.com/lycan-xx/studywise-ai/blob/main/client/src/pages/test-summary.tsx"
click node_clientapi "https://github.com/lycan-xx/studywise-ai/blob/main/client/src/services/apiService.ts"
click node_routes "https://github.com/lycan-xx/studywise-ai/blob/main/server/routes.ts"
click node_course "https://github.com/lycan-xx/studywise-ai/blob/main/server/controllers/CourseController.ts"
click node_moduletest "https://github.com/lycan-xx/studywise-ai/blob/main/server/controllers/ModuleTestController.ts"
click node_testctrl "https://github.com/lycan-xx/studywise-ai/blob/main/server/controllers/TestController.ts"
click node_results "https://github.com/lycan-xx/studywise-ai/blob/main/server/controllers/ResultsController.ts"
click node_aiengine "https://github.com/lycan-xx/studywise-ai/blob/main/server/services/AIService.ts"
click node_supabaseclient "https://github.com/lycan-xx/studywise-ai/blob/main/server/lib/supabase.ts"
click node_sourceproc "https://github.com/lycan-xx/studywise-ai/blob/main/client/src/utils/documentProcessor.ts"
click node_auth "https://github.com/lycan-xx/studywise-ai/blob/main/client/src/contexts/AuthContext.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_courseui,node_dashboard,node_testui,node_summaryui,node_clientapi,node_sourceproc,node_auth toneBlue
class node_routes,node_course,node_moduletest,node_testctrl,node_results toneAmber
class node_aiengine toneMint
class node_supabaseclient,node_database toneRose
class node_learner,node_provider toneIndigo
```

## Components

### Study client

- [App routing](https://github.com/lycan-xx/studywise-ai/blob/main/client/src/App.tsx): `client/src/App.tsx`
- [Course study](https://github.com/lycan-xx/studywise-ai/blob/main/client/src/components/course/ModuleContent.tsx): `client/src/components/course/ModuleContent.tsx`
- [Course creation](https://github.com/lycan-xx/studywise-ai/blob/main/client/src/pages/dashboard.tsx): `client/src/pages/dashboard.tsx`
- [Test taking](https://github.com/lycan-xx/studywise-ai/blob/main/client/src/pages/module-test.tsx): `client/src/pages/module-test.tsx`
- [Results views](https://github.com/lycan-xx/studywise-ai/blob/main/client/src/pages/test-summary.tsx): `client/src/pages/test-summary.tsx`
- [API client](https://github.com/lycan-xx/studywise-ai/blob/main/client/src/services/apiService.ts): `client/src/services/apiService.ts`
- [Document processing](https://github.com/lycan-xx/studywise-ai/blob/main/client/src/utils/documentProcessor.ts): `client/src/utils/documentProcessor.ts`
- [Authentication](https://github.com/lycan-xx/studywise-ai/blob/main/client/src/contexts/AuthContext.tsx): `client/src/contexts/AuthContext.tsx`

### Learning API

- [API routing](https://github.com/lycan-xx/studywise-ai/blob/main/server/routes.ts): `server/routes.ts`
- [Course generation](https://github.com/lycan-xx/studywise-ai/blob/main/server/controllers/CourseController.ts): `server/controllers/CourseController.ts`
- [Module tests](https://github.com/lycan-xx/studywise-ai/blob/main/server/controllers/ModuleTestController.ts): `server/controllers/ModuleTestController.ts`
- [Test operations](https://github.com/lycan-xx/studywise-ai/blob/main/server/controllers/TestController.ts): `server/controllers/TestController.ts`
- [Results analytics](https://github.com/lycan-xx/studywise-ai/blob/main/server/controllers/ResultsController.ts): `server/controllers/ResultsController.ts`

### AI generation

- [AI provider engine](https://github.com/lycan-xx/studywise-ai/blob/main/server/services/AIService.ts): `server/services/AIService.ts`

### Persistence and insights

- [Supabase access](https://github.com/lycan-xx/studywise-ai/blob/main/server/lib/supabase.ts): `server/lib/supabase.ts`
- **Supabase database**

### Other components

- **Learner**
- **AI providers**

## Connections

- Learner → App routing: uses (evidence: `client/src/App.tsx`)
- App routing → Course study: routes to (evidence: `client/src/App.tsx`)
- App routing → Course creation: routes to (evidence: `client/src/App.tsx`)
- App routing → Test taking: routes to (evidence: `client/src/App.tsx`)
- App routing → Results views: routes to (evidence: `client/src/App.tsx`)
- App routing → Authentication: provides (evidence: `client/src/App.tsx`)
- Course creation → Document processing: processes material
- Course creation → API client: requests generation
- Course study → API client: requests course data
- Test taking → API client: submits answers
- Results views → API client: requests results
- API client → API routing: calls API
- API routing → Course generation: dispatches (evidence: `server/routes.ts`)
- API routing → Module tests: dispatches (evidence: `server/routes.ts`)
- API routing → Test operations: dispatches (evidence: `server/routes.ts`)
- API routing → Results analytics: dispatches (evidence: `server/routes.ts`)
- Course generation → AI provider engine: generates course content (evidence: `server/controllers/CourseController.ts`)
- Course generation → Supabase access: stores course (evidence: `server/controllers/CourseController.ts`)
- Module tests → AI provider engine: generates questions (evidence: `server/controllers/ModuleTestController.ts`)
- Module tests → Supabase access: reads and writes tests (evidence: `server/controllers/ModuleTestController.ts`)
- Test operations → AI provider engine: generates questions (evidence: `server/controllers/TestController.ts`)
- Results analytics → Supabase access: reads performance (evidence: `server/controllers/ResultsController.ts`)
- AI provider engine → AI providers: sends prompts
- Supabase access → Supabase database: queries and persists (evidence: `server/lib/supabase.ts`)