# ravadakaran/vertexleam-ai architecture

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

- Interactive diagram: https://gitdiagram.com/ravadakaran/vertexleam-ai
- Repository: https://github.com/ravadakaran/vertexleam-ai

## Overview

VertexLearn AI is a role-based learning management system. The main journey starts with sign-in, proceeds through instructor course creation and admin approval, then student enrollment and a persisted learning workspace with lessons and assessments. Separate capabilities include course-grounded AI tutoring, discussions, notifications, analytics, personalization, and gamification. The graph combines documented capabilities with relationships visible in excerpts and the source index; unsampled wiring is left out rather than inferred.

Main entry points: [`backend/src/http.ts`](https://github.com/ravadakaran/vertexleam-ai/blob/main/backend/src/http.ts) (HTTP application), [`backend/src/modules/learning/routes.ts`](https://github.com/ravadakaran/vertexleam-ai/blob/main/backend/src/modules/learning/routes.ts) (Lessons and playback), [`frontend/src/pages/CourseWorkspace.tsx`](https://github.com/ravadakaran/vertexleam-ai/blob/main/frontend/src/pages/CourseWorkspace.tsx) (Course workspace), [`backend/src/modules/learning`](https://github.com/ravadakaran/vertexleam-ai/tree/main/backend/src/modules/learning) (Learning access and media)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_app["Role navigation<br/>[App.tsx]"]
  node_workspace["Workspace UI<br/>[Workspace.tsx]"]
  node_authform["Sign-in UI<br/>[AuthForm.tsx]"]
  node_session["Session state<br/>[auth.ts]"]
  node_api["Web API client<br/>[api.ts]"]
  node_courseui["Course workspace"]
  node_learningui["Learning dashboard<br/>[Learning.tsx]"]
  node_assessui["Assessments UI<br/>[Assessments.tsx]"]
  node_adminui["Admin panel<br/>[AdminPanel.tsx]"]
  node_coursecommunity["Course community UI"]
end

subgraph group_identity["Identity and governance"]
  node_authroutes["Authentication routes<br/>[routes.ts]"]
  node_authservice["Authentication service<br/>[service.ts]"]
  node_adminroutes["Governance routes<br/>[routes.ts]"]
end

subgraph group_learning["Courses and learning"]
  node_courses["Course catalog<br/>[service.ts]"]
  node_courseroutes["Course routes<br/>[routes.ts]"]
  node_enrollments["Enrollment service<br/>[service.ts]"]
  node_learningroutes["Lessons and playback<br/>[routes.ts]"]
  node_learninghelpers["Learning access and media"]
  node_assignments["Assignments<br/>[routes.ts]"]
  node_quizzes["Quizzes<br/>[routes.ts]"]
end

subgraph group_engagement["Learning engagement"]
  node_ai["AI tutor<br/>[routes.ts]"]
  node_personalization["Mastery and recommendations<br/>[routes.ts]"]
  node_discussions["Discussions<br/>[routes.ts]"]
  node_notifications["Notifications<br/>[routes.ts]"]
  node_gamification["Awards and leaderboard<br/>[routes.ts]"]
  node_analytics["Analytics<br/>[routes.ts]"]
end

subgraph group_platform["Service platform"]
  node_http["HTTP application<br/>[http.ts]"]
  node_authmiddleware["Authentication middleware<br/>[auth.ts]"]
  node_database[("PostgreSQL<br/>[index.ts]")]
  node_cache["Cache and limits<br/>[cache.ts]"]
  node_outbox["Event outbox<br/>[outbox.ts]"]
end

node_learner(("Learner"))
node_instructor(("Instructor"))
node_admin(("Administrator"))

node_learner -->|"signs in"| node_authform
node_instructor -->|"signs in"| node_authform
node_admin -->|"signs in"| node_authform
node_authform -->|"updates session"| node_session
node_session -->|"authenticates via"| node_authroutes
node_app -->|"checks role"| node_session
node_app -->|"renders"| node_workspace
node_workspace -.->|"hosts"| node_learningui
node_workspace -.->|"hosts"| node_adminui
node_learner -->|"views learning"| node_learningui
node_learningui -.->|"requests data"| node_api
node_instructor -->|"authors courses"| node_courseui
node_learner -->|"studies course"| node_courseui
node_courseui -->|"renders"| node_coursecommunity
node_courseui -->|"renders"| node_assessui
node_courseui -.->|"requests data"| node_api
node_admin -->|"governs courses"| node_adminui
node_adminui -.->|"requests data"| node_api
node_api -.->|"calls API"| node_http
node_http -.->|"routes requests"| node_authroutes
node_http -.->|"routes requests"| node_courseroutes
node_http -.->|"routes requests"| node_learningroutes
node_http -.->|"routes requests"| node_assignments
node_http -.->|"routes requests"| node_quizzes
node_http -.->|"routes requests"| node_ai
node_http -.->|"routes requests"| node_adminroutes
node_http -.->|"routes requests"| node_discussions
node_http -.->|"routes requests"| node_personalization
node_http -.->|"routes requests"| node_notifications
node_http -.->|"routes requests"| node_gamification
node_http -.->|"routes requests"| node_analytics
node_authroutes -->|"uses"| node_authmiddleware
node_authroutes -->|"delegates to"| node_authservice
node_adminroutes -->|"queries"| node_database
node_adminroutes -->|"checks scope"| node_learninghelpers
node_courseroutes -->|"uses"| node_authmiddleware
node_courseroutes -->|"delegates to"| node_courses
node_courseroutes -->|"delegates to"| node_enrollments
node_learningroutes -->|"queries"| node_database
node_learningroutes -->|"loads course view"| node_courses
node_learningroutes -->|"checks scope"| node_learninghelpers
node_learningroutes -->|"stores playback"| node_database
node_assignments -->|"checks scope"| node_learninghelpers
node_assignments -->|"limits uploads"| node_cache
node_quizzes -->|"checks scope"| node_learninghelpers
node_quizzes -->|"stores attempts"| node_database
node_ai -->|"checks course access"| node_learninghelpers
node_ai -->|"stores tutor sessions"| node_database

click node_app "https://github.com/ravadakaran/vertexleam-ai/blob/main/frontend/src/routes/App.tsx"
click node_workspace "https://github.com/ravadakaran/vertexleam-ai/blob/main/frontend/src/layouts/Workspace.tsx"
click node_authform "https://github.com/ravadakaran/vertexleam-ai/blob/main/frontend/src/pages/auth/AuthForm.tsx"
click node_session "https://github.com/ravadakaran/vertexleam-ai/blob/main/frontend/src/auth.ts"
click node_api "https://github.com/ravadakaran/vertexleam-ai/blob/main/frontend/src/api.ts"
click node_courseui "https://github.com/ravadakaran/vertexleam-ai/blob/main/frontend/src/pages/CourseWorkspace.tsx"
click node_learningui "https://github.com/ravadakaran/vertexleam-ai/blob/main/frontend/src/pages/Learning.tsx"
click node_assessui "https://github.com/ravadakaran/vertexleam-ai/blob/main/frontend/src/pages/Assessments.tsx"
click node_adminui "https://github.com/ravadakaran/vertexleam-ai/blob/main/frontend/src/pages/AdminPanel.tsx"
click node_coursecommunity "https://github.com/ravadakaran/vertexleam-ai/blob/main/frontend/src/components/CourseCommunity.tsx"
click node_authroutes "https://github.com/ravadakaran/vertexleam-ai/blob/main/backend/src/modules/auth/routes.ts"
click node_authservice "https://github.com/ravadakaran/vertexleam-ai/blob/main/backend/src/modules/auth/service.ts"
click node_adminroutes "https://github.com/ravadakaran/vertexleam-ai/blob/main/backend/src/modules/admin/routes.ts"
click node_courses "https://github.com/ravadakaran/vertexleam-ai/blob/main/backend/src/modules/courses/service.ts"
click node_courseroutes "https://github.com/ravadakaran/vertexleam-ai/blob/main/backend/src/modules/courses/routes.ts"
click node_enrollments "https://github.com/ravadakaran/vertexleam-ai/blob/main/backend/src/modules/enrollments/service.ts"
click node_learningroutes "https://github.com/ravadakaran/vertexleam-ai/blob/main/backend/src/modules/learning/routes.ts"
click node_learninghelpers "https://github.com/ravadakaran/vertexleam-ai/tree/main/backend/src/modules/learning"
click node_assignments "https://github.com/ravadakaran/vertexleam-ai/blob/main/backend/src/modules/assignments/routes.ts"
click node_quizzes "https://github.com/ravadakaran/vertexleam-ai/blob/main/backend/src/modules/quizzes/routes.ts"
click node_ai "https://github.com/ravadakaran/vertexleam-ai/blob/main/backend/src/modules/ai/routes.ts"
click node_personalization "https://github.com/ravadakaran/vertexleam-ai/blob/main/backend/src/modules/personalization/routes.ts"
click node_discussions "https://github.com/ravadakaran/vertexleam-ai/blob/main/backend/src/modules/discussions/routes.ts"
click node_notifications "https://github.com/ravadakaran/vertexleam-ai/blob/main/backend/src/modules/notifications/routes.ts"
click node_gamification "https://github.com/ravadakaran/vertexleam-ai/blob/main/backend/src/modules/gamification/routes.ts"
click node_analytics "https://github.com/ravadakaran/vertexleam-ai/blob/main/backend/src/modules/analytics/routes.ts"
click node_http "https://github.com/ravadakaran/vertexleam-ai/blob/main/backend/src/http.ts"
click node_authmiddleware "https://github.com/ravadakaran/vertexleam-ai/blob/main/backend/src/middleware/auth.ts"
click node_database "https://github.com/ravadakaran/vertexleam-ai/blob/main/backend/src/db/index.ts"
click node_cache "https://github.com/ravadakaran/vertexleam-ai/blob/main/backend/src/cache.ts"
click node_outbox "https://github.com/ravadakaran/vertexleam-ai/blob/main/backend/src/jobs/outbox.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_workspace,node_authform,node_session,node_api,node_courseui,node_learningui,node_assessui,node_adminui,node_coursecommunity toneBlue
class node_authroutes,node_authservice,node_adminroutes toneAmber
class node_courses,node_courseroutes,node_enrollments,node_learningroutes,node_learninghelpers,node_assignments,node_quizzes toneMint
class node_ai,node_personalization,node_discussions,node_notifications,node_gamification,node_analytics toneRose
class node_http,node_authmiddleware,node_database,node_cache,node_outbox,node_learner,node_instructor,node_admin toneIndigo
```

## Components

### Web experience

- [Role navigation](https://github.com/ravadakaran/vertexleam-ai/blob/main/frontend/src/routes/App.tsx): `frontend/src/routes/App.tsx`
- [Workspace UI](https://github.com/ravadakaran/vertexleam-ai/blob/main/frontend/src/layouts/Workspace.tsx): `frontend/src/layouts/Workspace.tsx`
- [Sign-in UI](https://github.com/ravadakaran/vertexleam-ai/blob/main/frontend/src/pages/auth/AuthForm.tsx): `frontend/src/pages/auth/AuthForm.tsx`
- [Session state](https://github.com/ravadakaran/vertexleam-ai/blob/main/frontend/src/auth.ts): `frontend/src/auth.ts`
- [Web API client](https://github.com/ravadakaran/vertexleam-ai/blob/main/frontend/src/api.ts): `frontend/src/api.ts`
- [Course workspace](https://github.com/ravadakaran/vertexleam-ai/blob/main/frontend/src/pages/CourseWorkspace.tsx): `frontend/src/pages/CourseWorkspace.tsx`
- [Learning dashboard](https://github.com/ravadakaran/vertexleam-ai/blob/main/frontend/src/pages/Learning.tsx): `frontend/src/pages/Learning.tsx`
- [Assessments UI](https://github.com/ravadakaran/vertexleam-ai/blob/main/frontend/src/pages/Assessments.tsx): `frontend/src/pages/Assessments.tsx`
- [Admin panel](https://github.com/ravadakaran/vertexleam-ai/blob/main/frontend/src/pages/AdminPanel.tsx): `frontend/src/pages/AdminPanel.tsx`
- [Course community UI](https://github.com/ravadakaran/vertexleam-ai/blob/main/frontend/src/components/CourseCommunity.tsx): `frontend/src/components/CourseCommunity.tsx`

### Identity and governance

- [Authentication routes](https://github.com/ravadakaran/vertexleam-ai/blob/main/backend/src/modules/auth/routes.ts): `backend/src/modules/auth/routes.ts`
- [Authentication service](https://github.com/ravadakaran/vertexleam-ai/blob/main/backend/src/modules/auth/service.ts): `backend/src/modules/auth/service.ts`
- [Governance routes](https://github.com/ravadakaran/vertexleam-ai/blob/main/backend/src/modules/admin/routes.ts): `backend/src/modules/admin/routes.ts`

### Courses and learning

- [Course catalog](https://github.com/ravadakaran/vertexleam-ai/blob/main/backend/src/modules/courses/service.ts): `backend/src/modules/courses/service.ts`
- [Course routes](https://github.com/ravadakaran/vertexleam-ai/blob/main/backend/src/modules/courses/routes.ts): `backend/src/modules/courses/routes.ts`
- [Enrollment service](https://github.com/ravadakaran/vertexleam-ai/blob/main/backend/src/modules/enrollments/service.ts): `backend/src/modules/enrollments/service.ts`
- [Lessons and playback](https://github.com/ravadakaran/vertexleam-ai/blob/main/backend/src/modules/learning/routes.ts): `backend/src/modules/learning/routes.ts`
- [Learning access and media](https://github.com/ravadakaran/vertexleam-ai/tree/main/backend/src/modules/learning): `backend/src/modules/learning`
- [Assignments](https://github.com/ravadakaran/vertexleam-ai/blob/main/backend/src/modules/assignments/routes.ts): `backend/src/modules/assignments/routes.ts`
- [Quizzes](https://github.com/ravadakaran/vertexleam-ai/blob/main/backend/src/modules/quizzes/routes.ts): `backend/src/modules/quizzes/routes.ts`

### Learning engagement

- [AI tutor](https://github.com/ravadakaran/vertexleam-ai/blob/main/backend/src/modules/ai/routes.ts): `backend/src/modules/ai/routes.ts`
- [Mastery and recommendations](https://github.com/ravadakaran/vertexleam-ai/blob/main/backend/src/modules/personalization/routes.ts): `backend/src/modules/personalization/routes.ts`
- [Discussions](https://github.com/ravadakaran/vertexleam-ai/blob/main/backend/src/modules/discussions/routes.ts): `backend/src/modules/discussions/routes.ts`
- [Notifications](https://github.com/ravadakaran/vertexleam-ai/blob/main/backend/src/modules/notifications/routes.ts): `backend/src/modules/notifications/routes.ts`
- [Awards and leaderboard](https://github.com/ravadakaran/vertexleam-ai/blob/main/backend/src/modules/gamification/routes.ts): `backend/src/modules/gamification/routes.ts`
- [Analytics](https://github.com/ravadakaran/vertexleam-ai/blob/main/backend/src/modules/analytics/routes.ts): `backend/src/modules/analytics/routes.ts`

### Service platform

- [HTTP application](https://github.com/ravadakaran/vertexleam-ai/blob/main/backend/src/http.ts): `backend/src/http.ts`
- [Authentication middleware](https://github.com/ravadakaran/vertexleam-ai/blob/main/backend/src/middleware/auth.ts): `backend/src/middleware/auth.ts`
- [PostgreSQL](https://github.com/ravadakaran/vertexleam-ai/blob/main/backend/src/db/index.ts): `backend/src/db/index.ts`
- [Cache and limits](https://github.com/ravadakaran/vertexleam-ai/blob/main/backend/src/cache.ts): `backend/src/cache.ts`
- [Event outbox](https://github.com/ravadakaran/vertexleam-ai/blob/main/backend/src/jobs/outbox.ts): `backend/src/jobs/outbox.ts`

### Other components

- **Learner**
- **Instructor**
- **Administrator**

## Connections

- Learner → Sign-in UI: signs in
- Instructor → Sign-in UI: signs in
- Administrator → Sign-in UI: signs in
- Sign-in UI → Session state: updates session (evidence: `frontend/src/pages/auth/AuthForm.tsx`)
- Session state → Authentication routes: authenticates via (evidence: `frontend/src/auth.ts`)
- Role navigation → Session state: checks role (evidence: `frontend/src/routes/App.tsx`)
- Role navigation → Workspace UI: renders (evidence: `frontend/src/routes/App.tsx`)
- Workspace UI → Learning dashboard: hosts
- Workspace UI → Admin panel: hosts
- Learner → Learning dashboard: views learning
- Learning dashboard → Web API client: requests data
- Instructor → Course workspace: authors courses (evidence: `README.md`)
- Learner → Course workspace: studies course (evidence: `README.md`)
- Course workspace → Course community UI: renders (evidence: `frontend/src/pages/CourseWorkspace.tsx`)
- Course workspace → Assessments UI: renders (evidence: `frontend/src/pages/CourseWorkspace.tsx`)
- Course workspace → Web API client: requests data (evidence: `frontend/src/pages/CourseWorkspace.tsx`)
- Administrator → Admin panel: governs courses (evidence: `README.md`)
- Admin panel → Web API client: requests data
- Web API client → HTTP application: calls API
- HTTP application → Authentication routes: routes requests (evidence: `backend/src/modules/auth/routes.ts`)
- HTTP application → Course routes: routes requests (evidence: `backend/src/modules/courses/routes.ts`)
- HTTP application → Lessons and playback: routes requests (evidence: `backend/src/modules/learning/routes.ts`)
- HTTP application → Assignments: routes requests (evidence: `backend/src/modules/assignments/routes.ts`)
- HTTP application → Quizzes: routes requests (evidence: `backend/src/modules/quizzes/routes.ts`)
- HTTP application → AI tutor: routes requests (evidence: `backend/src/modules/ai/routes.ts`)
- HTTP application → Governance routes: routes requests (evidence: `backend/src/modules/admin/routes.ts`)
- HTTP application → Discussions: routes requests (evidence: `backend/src/modules/discussions/routes.ts`)
- HTTP application → Mastery and recommendations: routes requests (evidence: `backend/src/modules/personalization/routes.ts`)
- HTTP application → Notifications: routes requests (evidence: `backend/src/modules/notifications/routes.ts`)
- HTTP application → Awards and leaderboard: routes requests (evidence: `backend/src/modules/gamification/routes.ts`)
- HTTP application → Analytics: routes requests (evidence: `backend/src/modules/analytics/routes.ts`)
- Authentication routes → Authentication middleware: uses (evidence: `backend/src/modules/auth/routes.ts`)
- Authentication routes → Authentication service: delegates to (evidence: `backend/src/modules/auth/routes.ts`)
- Governance routes → PostgreSQL: queries (evidence: `backend/src/modules/admin/routes.ts`)
- Governance routes → Learning access and media: checks scope (evidence: `backend/src/modules/admin/routes.ts`)
- Course routes → Authentication middleware: uses (evidence: `backend/src/modules/courses/routes.ts`)
- Course routes → Course catalog: delegates to (evidence: `backend/src/modules/courses/routes.ts`)
- Course routes → Enrollment service: delegates to (evidence: `backend/src/modules/courses/routes.ts`)
- Lessons and playback → PostgreSQL: queries (evidence: `backend/src/modules/learning/routes.ts`)
- Lessons and playback → Course catalog: loads course view (evidence: `backend/src/modules/learning/routes.ts`)
- Lessons and playback → Learning access and media: checks scope (evidence: `backend/src/modules/learning/routes.ts`)
- Lessons and playback → PostgreSQL: stores playback (evidence: `backend/src/modules/learning/routes.ts`)
- Assignments → Learning access and media: checks scope (evidence: `backend/src/modules/assignments/routes.ts`)
- Assignments → Cache and limits: limits uploads (evidence: `backend/src/modules/assignments/routes.ts`)
- Quizzes → Learning access and media: checks scope (evidence: `backend/src/modules/quizzes/routes.ts`)
- Quizzes → PostgreSQL: stores attempts (evidence: `backend/src/modules/quizzes/routes.ts`)
- AI tutor → Learning access and media: checks course access (evidence: `backend/src/modules/ai/routes.ts`)
- AI tutor → PostgreSQL: stores tutor sessions (evidence: `backend/src/modules/ai/routes.ts`)