# manavalan2517/ai-lms architecture

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

- Interactive diagram: https://gitdiagram.com/manavalan2517/ai-lms
- Repository: https://github.com/manavalan2517/ai-lms

## Overview

1. This repository is a Next.js App Router application for an AI-powered LMS. The core architecture is split into three layers: UI pages under `app/`, HTTP API routes under `app/api/`, and asynchronous background work under `inngest/`. Persistent state lives in a PostgreSQL database accessed through Drizzle ORM.

2. Authentication is handled by Clerk and integrated at the app boundary. The `app/(auth)` route group contains sign-in and sign-up screens, while `middleware.js` likely protects authenticated routes and redirects unauthenticated users. `app/provider.js` and the root layout wire Clerk context into the client UI.

3. The main user-facing flows are organized by route: `app/create` for starting a new learning plan, `app/dashboard` for listing and tracking courses, and `app/course/[courseId]` for viewing an individual course. The course area is further subdivided into notes, flashcards, quiz, and Q&A pages, each with its own UI components.

4. Course creation is a two-step pipeline. The create page collects topic, course type, and difficulty, then calls `/api/generate-course-outline`. That endpoint creates the course record and triggers AI generation of the outline. The generated outline becomes the parent structure for all later study materials.

5. Study material generation is intentionally asynchronous. `/api/study-type-content` triggers Inngest jobs for flashcards, quizzes, and Q&A, rather than generating everything inline in the request. This lets the UI show “generating” states while the background workers produce content and update database status fields.

6. Notes appear to be generated as part of the course outline pipeline, while flashcards/quiz/Q&A are generated per chapter or study type. The readme indicates notes are stored as markdown, and the course pages render them with markdown tooling. This means content is structured in the database but presented as rich text in the UI.

7. The database boundary is centralized in `configs/db.js` and `configs/schema.js`, with Drizzle ORM defining the data model. The schema likely includes users, courses, chapters, and study-material tables or fields for statuses and generated content. All API routes and Inngest functions use this shared schema rather than duplicating persistence logic.

8. Inngest is the orchestration layer for side effects. `inngest/client.js` and `inngest/functions.js` define event-driven jobs such as user creation sync, course-outline generation, note generation, and study-type generation. `app/api/inngest/route.js` exposes the webhook/handler endpoint that Inngest uses to run these jobs.

9. The AI boundary is isolated in `configs/AiModel.js`. That file likely encapsulates Gemini model setup and prompt templates so the rest of the code only deals with “generate outline,” “generate notes,” or “generate flashcards” operations. This keeps AI prompting and model selection separate from routing and persistence.

10. The dashboard is the operational hub for a logged-in user. Its components show course cards, progress, alerts, loading states, and a welcome banner. That suggests the dashboard reads course rows from the database and reflects generation status rather than recomputing anything locally.

11. The course detail area is built as a nested layout with reusable section components. `CourseIntroCard`, `ChapterList`, and `StudyMaterialSection` form the top-level structure, while the flashcard subroute uses Swiper and flip-card UI, the quiz subroute provides interactive scoring/timers, and the notes/Q&A views focus on markdown rendering.

12. Overall data flow: user authenticates with Clerk → creates a course from the create page → API persists the course and enqueues Inngest jobs → Gemini generates outline and study content → Drizzle writes results and status back to Postgres → dashboard and course pages read the stored course/material data and render the appropriate study experience. The main architectural boundary is between synchronous request/response endpoints and asynchronous AI generation workers.

Main entry points: [`app/course/layout.jsx`](https://github.com/manavalan2517/ai-lms/blob/main/app/course/layout.jsx) (Course Layout), [`configs/db.js`](https://github.com/manavalan2517/ai-lms/blob/main/configs/db.js) (Database), [`app/api/generate-course-outline/route.js`](https://github.com/manavalan2517/ai-lms/blob/main/app/api/generate-course-outline/route.js) (Outline API), [`inngest/functions.js`](https://github.com/manavalan2517/ai-lms/blob/main/inngest/functions.js) (Jobs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_app["App Router"]
  node_node_root_layout["Root Layout<br/>Next.js shell<br/>[layout.js]"]
  node_node_provider["Provider<br/>[provider.js]"]
  node_node_middleware["Middleware<br/>Route guard<br/>[middleware.js]"]
  node_node_auth_routes["Auth Pages<br/>Clerk UI"]
  node_node_create_page["Create Flow<br/>Course setup UI<br/>[page.jsx]"]
  node_node_dashboard_page["Dashboard<br/>Course hub<br/>[page.jsx]"]
  node_node_course_layout["Course Layout<br/>Nested layout<br/>[layout.jsx]"]
  node_node_course_overview["Course View<br/>Course detail<br/>[page.jsx]"]
  node_node_notes_page["Notes<br/>Markdown view<br/>[page.jsx]"]
  node_node_flashcards_page["Flashcards<br/>Study UI<br/>[page.jsx]"]
  node_node_quiz_page["Quiz<br/>Assessment UI<br/>[page.jsx]"]
  node_node_qa_page["Q&A<br/>Study UI<br/>[page.jsx]"]
end

subgraph group_group_api["API Layer"]
  node_node_course_api["Courses API<br/>Course data endpoint<br/>[route.js]"]
  node_node_create_user_api["Create User<br/>Clerk sync endpoint<br/>[route.js]"]
  node_node_outline_api["Outline API<br/>Generation endpoint<br/>[route.js]"]
  node_node_study_type_api["Study Type API<br/>Generation trigger<br/>[route.jsx]"]
  node_node_study_content_api["Study Content API<br/>Job trigger<br/>[route.jsx]"]
  node_node_inngest_route["Inngest Hook<br/>Webhook handler<br/>[route.js]"]
end

subgraph group_group_core["Core Services"]
  node_node_db[("Database<br/>Postgres access<br/>[db.js]")]
  node_node_schema["Schema<br/>Drizzle models<br/>[schema.js]"]
  node_node_ai["AI Model<br/>Gemini wrapper<br/>[AiModel.js]"]
  node_node_inngest_client["Inngest Client<br/>Event client<br/>[client.js]"]
  node_node_inngest_functions["Jobs<br/>Event workers<br/>[functions.js]"]
end

node_node_root_layout -->|"wraps"| node_node_provider
node_node_middleware -->|"guards"| node_node_auth_routes
node_node_auth_routes -->|"uses"| node_node_provider
node_node_create_page -->|"submits"| node_node_outline_api
node_node_dashboard_page -->|"reads"| node_node_course_api
node_node_course_layout -->|"wraps"| node_node_course_overview
node_node_course_layout -->|"routes to"| node_node_notes_page
node_node_course_layout -->|"routes to"| node_node_flashcards_page
node_node_course_layout -->|"routes to"| node_node_quiz_page
node_node_course_layout -->|"routes to"| node_node_qa_page
node_node_outline_api -->|"writes"| node_node_db
node_node_outline_api -->|"calls"| node_node_ai
node_node_outline_api -->|"emits"| node_node_inngest_client
node_node_study_type_api -->|"emits"| node_node_inngest_client
node_node_study_content_api -->|"emits"| node_node_inngest_client
node_node_inngest_route -->|"serves"| node_node_inngest_functions
node_node_inngest_functions -->|"calls"| node_node_ai
node_node_inngest_functions -->|"updates"| node_node_db
node_node_db -->|"conforms to"| node_node_schema
node_node_create_user_api -->|"writes"| node_node_db
node_node_course_api -->|"reads"| node_node_db

click node_node_root_layout "https://github.com/manavalan2517/ai-lms/blob/main/app/layout.js"
click node_node_provider "https://github.com/manavalan2517/ai-lms/blob/main/app/provider.js"
click node_node_middleware "https://github.com/manavalan2517/ai-lms/blob/main/middleware.js"
click node_node_auth_routes "https://github.com/manavalan2517/ai-lms/tree/main/app/(auth)"
click node_node_create_page "https://github.com/manavalan2517/ai-lms/blob/main/app/create/page.jsx"
click node_node_dashboard_page "https://github.com/manavalan2517/ai-lms/blob/main/app/dashboard/page.jsx"
click node_node_course_layout "https://github.com/manavalan2517/ai-lms/blob/main/app/course/layout.jsx"
click node_node_course_overview "https://github.com/manavalan2517/ai-lms/blob/main/app/course/[courseId]/page.jsx"
click node_node_notes_page "https://github.com/manavalan2517/ai-lms/blob/main/app/course/[courseId]/notes/page.jsx"
click node_node_flashcards_page "https://github.com/manavalan2517/ai-lms/blob/main/app/course/[courseId]/flashcards/page.jsx"
click node_node_quiz_page "https://github.com/manavalan2517/ai-lms/blob/main/app/course/[courseId]/quiz/page.jsx"
click node_node_qa_page "https://github.com/manavalan2517/ai-lms/blob/main/app/course/[courseId]/qa/page.jsx"
click node_node_course_api "https://github.com/manavalan2517/ai-lms/blob/main/app/api/courses/route.js"
click node_node_create_user_api "https://github.com/manavalan2517/ai-lms/blob/main/app/api/create-user/route.js"
click node_node_outline_api "https://github.com/manavalan2517/ai-lms/blob/main/app/api/generate-course-outline/route.js"
click node_node_study_type_api "https://github.com/manavalan2517/ai-lms/blob/main/app/api/study-type/route.jsx"
click node_node_study_content_api "https://github.com/manavalan2517/ai-lms/blob/main/app/api/study-type-content/route.jsx"
click node_node_inngest_route "https://github.com/manavalan2517/ai-lms/blob/main/app/api/inngest/route.js"
click node_node_db "https://github.com/manavalan2517/ai-lms/blob/main/configs/db.js"
click node_node_schema "https://github.com/manavalan2517/ai-lms/blob/main/configs/schema.js"
click node_node_ai "https://github.com/manavalan2517/ai-lms/blob/main/configs/AiModel.js"
click node_node_inngest_client "https://github.com/manavalan2517/ai-lms/blob/main/inngest/client.js"
click node_node_inngest_functions "https://github.com/manavalan2517/ai-lms/blob/main/inngest/functions.js"

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_node_root_layout,node_node_provider,node_node_middleware,node_node_auth_routes,node_node_create_page,node_node_dashboard_page,node_node_course_layout,node_node_course_overview,node_node_notes_page,node_node_flashcards_page,node_node_quiz_page,node_node_qa_page toneBlue
class node_node_course_api,node_node_create_user_api,node_node_outline_api,node_node_study_type_api,node_node_study_content_api,node_node_inngest_route toneAmber
class node_node_db,node_node_schema,node_node_ai,node_node_inngest_client,node_node_inngest_functions toneMint
```

## Components

### App Router

User-facing routes, layouts, and page flows

- [Root Layout](https://github.com/manavalan2517/ai-lms/blob/main/app/layout.js): Next.js shell · Global app shell and shared providers · `app/layout.js`
- [Provider](https://github.com/manavalan2517/ai-lms/blob/main/app/provider.js): Client providers · Wires shared client context such as authentication · `app/provider.js`
- [Middleware](https://github.com/manavalan2517/ai-lms/blob/main/middleware.js): Route guard · Protects routes and handles auth redirects · `middleware.js`
- [Auth Pages](https://github.com/manavalan2517/ai-lms/tree/main/app/(auth)): Clerk UI · Sign-in and sign-up route group · `app/(auth)`
- [Create Flow](https://github.com/manavalan2517/ai-lms/blob/main/app/create/page.jsx): Course setup UI · Collects topic and course parameters before generation · `app/create/page.jsx`
- [Dashboard](https://github.com/manavalan2517/ai-lms/blob/main/app/dashboard/page.jsx): Course hub · Shows course list, progress, alerts, and loading states · `app/dashboard/page.jsx`
- [Course Layout](https://github.com/manavalan2517/ai-lms/blob/main/app/course/layout.jsx): Nested layout · Shared shell for course detail subroutes · `app/course/layout.jsx`
- [Course View](https://github.com/manavalan2517/ai-lms/blob/main/app/course/[courseId]/page.jsx): Course detail · Main course page with intro and chapter navigation · `app/course/[courseId]/page.jsx`
- [Notes](https://github.com/manavalan2517/ai-lms/blob/main/app/course/[courseId]/notes/page.jsx): Markdown view · Renders generated notes for a course · `app/course/[courseId]/notes/page.jsx`
- [Flashcards](https://github.com/manavalan2517/ai-lms/blob/main/app/course/[courseId]/flashcards/page.jsx): Study UI · Interactive flashcard study experience · `app/course/[courseId]/flashcards/page.jsx`
- [Quiz](https://github.com/manavalan2517/ai-lms/blob/main/app/course/[courseId]/quiz/page.jsx): Assessment UI · Timed quiz and scoring experience · `app/course/[courseId]/quiz/page.jsx`
- [Q&A](https://github.com/manavalan2517/ai-lms/blob/main/app/course/[courseId]/qa/page.jsx): Study UI · Question and answer study view · `app/course/[courseId]/qa/page.jsx`

### API Layer

HTTP endpoints for persistence and AI orchestration

- [Courses API](https://github.com/manavalan2517/ai-lms/blob/main/app/api/courses/route.js): Course data endpoint · Reads and serves course records · `app/api/courses/route.js`
- [Create User](https://github.com/manavalan2517/ai-lms/blob/main/app/api/create-user/route.js): Clerk sync endpoint · Creates or syncs user records after auth events · `app/api/create-user/route.js`
- [Outline API](https://github.com/manavalan2517/ai-lms/blob/main/app/api/generate-course-outline/route.js): Generation endpoint · Persists a course and starts outline generation · `app/api/generate-course-outline/route.js`
- [Study Type API](https://github.com/manavalan2517/ai-lms/blob/main/app/api/study-type/route.jsx): Generation trigger · Starts asynchronous study content jobs · `app/api/study-type/route.jsx`
- [Study Content API](https://github.com/manavalan2517/ai-lms/blob/main/app/api/study-type-content/route.jsx): Job trigger · Enqueues flashcard, quiz, and Q&A generation · `app/api/study-type-content/route.jsx`
- [Inngest Hook](https://github.com/manavalan2517/ai-lms/blob/main/app/api/inngest/route.js): Webhook handler · Receives Inngest event deliveries · `app/api/inngest/route.js`

### Core Services

Shared database, AI, and background job infrastructure

- [Database](https://github.com/manavalan2517/ai-lms/blob/main/configs/db.js): Postgres access · Shared Drizzle connection to persistent storage · `configs/db.js`
- [Schema](https://github.com/manavalan2517/ai-lms/blob/main/configs/schema.js): Drizzle models · Central data model for users, courses, chapters, and materials · `configs/schema.js`
- [AI Model](https://github.com/manavalan2517/ai-lms/blob/main/configs/AiModel.js): Gemini wrapper · Encapsulates prompting and model calls for content generation · `configs/AiModel.js`
- [Inngest Client](https://github.com/manavalan2517/ai-lms/blob/main/inngest/client.js): Event client · Defines the application event bus integration · `inngest/client.js`
- [Jobs](https://github.com/manavalan2517/ai-lms/blob/main/inngest/functions.js): Event workers · Runs outline, notes, and study material background tasks · `inngest/functions.js`

## Connections

- Root Layout → Provider: wraps · Root layout injects shared client providers
- Middleware → Auth Pages: guards · Protects authenticated areas and routes unauthenticated users
- Auth Pages → Provider: uses · Auth UI depends on app-wide provider context
- Create Flow → Outline API: submits · Create flow sends course setup data to the outline endpoint
- Dashboard → Courses API: reads · Dashboard loads user courses and progress
- Course Layout → Course View: wraps · Shared course shell contains the main course view
- Course Layout → Notes: routes to · Layout serves the notes subroute
- Course Layout → Flashcards: routes to · Layout serves the flashcards subroute
- Course Layout → Quiz: routes to · Layout serves the quiz subroute
- Course Layout → Q&A: routes to · Layout serves the Q&A subroute
- Outline API → Database: writes · Persists the course before generation starts
- Outline API → AI Model: calls · Uses AI to generate the course outline and notes
- Outline API → Inngest Client: emits · Triggers event-driven background processing
- Study Type API → Inngest Client: emits · Starts asynchronous study material jobs
- Study Content API → Inngest Client: emits · Enqueues study content generation tasks
- Inngest Hook → Jobs: serves · Webhook handler executes registered background jobs
- Jobs → AI Model: calls · Workers generate outlines, notes, and study content
- Jobs → Database: updates · Workers persist generated content and status fields
- Database → Schema: conforms to · Database access is structured by the shared schema
- Create User → Database: writes · Syncs user records into Postgres
- Courses API → Database: reads · Serves stored course data to the UI
