# ClassBuddy 🎓 — Next-Gen AI EdTech & Real-Time Classroom Ecosystem [![License](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](LICENSE) [![OAuth2](https://img.shields.io/badge/OAuth2-Custom_Authorization_Server_PKCE-FF6F00?logo=oauth&logoColor=white&style=flat-square)](#-1-custom-oauth-20-authorization-server-pkce) [![React](https://img.shields.io/badge/React-18.3-61DAFB?logo=react&logoColor=black&style=flat-square)](https://react.dev/) [![TypeScript](https://img.shields.io/badge/TypeScript-5.8-3178C6?logo=typescript&logoColor=white&style=flat-square)](https://www.typescriptlang.org/) [![Vite](https://img.shields.io/badge/Vite-7.1-646CFF?logo=vite&logoColor=white&style=flat-square)](https://vitejs.dev/) [![FastAPI](https://img.shields.io/badge/FastAPI-0.109-009688?logo=fastapi&logoColor=white&style=flat-square)](https://fastapi.tiangolo.com/) [![TailwindCSS](https://img.shields.io/badge/Tailwind_CSS-4.1-38B2AC?logo=tailwind-css&logoColor=white&style=flat-square)](https://tailwindcss.com/) [![PostgreSQL](https://img.shields.io/badge/PostgreSQL-NeonDB-4169E1?logo=postgresql&logoColor=white&style=flat-square)](https://www.postgresql.org/) [![Redis](https://img.shields.io/badge/Redis-PubSub-DC382D?logo=redis&logoColor=white&style=flat-square)](https://redis.io/) [![Inngest](https://img.shields.io/badge/Inngest-Background_Jobs-FF5722?logo=inngest&logoColor=white&style=flat-square)](#-2-event-driven-background-engine--cron-schedulers-inngest) [![LangChain](https://img.shields.io/badge/LangChain-Agentic-1C3C3A?logo=langchain&logoColor=white&style=flat-square)](https://www.langchain.com/) [![Docker](https://img.shields.io/badge/Docker-Enabled-2496ED?logo=docker&logoColor=white&style=flat-square)](https://www.docker.com/) > **Project Links & References:** > 🔗 **Web Repository:** [GitHub - ClassBuddy](https://github.com/Sandeep-singh-99/ClassBuddy) > 📱 **Android Client:** [GitHub - ClassBuddy Mobile App](https://github.com/Sandeep-singh-99/ClassBuddy_App) > 🌐 **Domain:** Multi-Agent AI Systems, Distributed Real-Time Microservices, EdTech, Cloud Architecture --- ## 📌 Executive Overview **ClassBuddy** is a modern, enterprise-grade educational ecosystem engineered to connect educators and learners through autonomous AI agents, distributed low-latency messaging, automated assignment evaluation, and built-in subscription monetization. Designed from the ground up to solve the architectural bottlenecks of AI-native web applications, ClassBuddy features a custom-built **OAuth 2.0 PKCE Authorization Server** (eliminating third-party auth vendors), a **LangGraph multi-agent self-refining loop**, an **Inngest event-driven background job engine with Cron automation**, a **Redis-backed distributed WebSocket mesh**, and **real-time token streaming via Server-Sent Events (SSE)**. --- ## 💻 Tech Stack for Portfolio (Comma-Separated) ### 🏷️ Categorized by Engineering Domain: * **Frontend Architecture:** React 18.3, Vite 7.1, TypeScript 5.8, Tailwind CSS 4.1, Redux Toolkit, Redux Persist, TanStack Query v5, Radix UI Primitives, Lucide Icons, Recharts, React MD Editor, Axios * **Backend & Core API:** FastAPI 0.109 (Async Python 3.10+), SQLAlchemy 2.0, Alembic Migrations, PostgreSQL (Neon Cloud Serverless), SlowAPI (Token Bucket Rate Limiting), WebSockets, Server-Sent Events (SSE) * **Authentication & Identity:** Custom Standalone OAuth 2.0 Server, RFC 7636 PKCE (`S256` Challenge Verifier), Refresh Token Family Rotation, HttpOnly Strict Cookies, Mobile Bearer Tokens, PyJWT * **Autonomous AI & Agentic Systems:** LangChain, LangGraph State Machines (Planner ➔ Research ➔ Generator ➔ Evaluator ➔ Improver ➔ Saver), Google Gemini 2.5 Flash, Hugging Face Hub, Tavily Search API * **Asynchronous Jobs & Distributed Systems:** Inngest Serverless Event Bus, Inngest Cron Schedulers, Redis 7 (Pub/Sub Broker & KV Caching), Cloudinary CDN, Razorpay Payments API, Docker, Docker Compose --- ## 🏗️ System Design Architecture ClassBuddy decouples compute-heavy agentic execution, high-concurrency WebSocket messaging, and transactional relational operations into an event-driven, resilient architecture: ```mermaid graph TD subgraph Clients [Clients Layer] Web[React 18 / Vite 7 Web App] Android[Android Native Mobile App] end subgraph AuthServer [Custom OAuth 2.0 PKCE Server] OAuth_Endpoint[OAuth2 /oauth Endpoints] PKCE_Val[PKCE S256 Code Verifier] Cookie_Mgr[HttpOnly Secure Cookie Manager] Token_Family[Token Family Reuse Detector] end subgraph API_Gateway [FastAPI Gateway Core] FA[FastAPI Server Engine] RL[SlowAPI Rate Limiter] Teacher_Guard[Teacher Group Ownership Guard] WS_Manager[Distributed WebSocket Manager] SSE_Stream[SSE Real-Time AI Streamer] end subgraph Realtime_PubSub [Real-Time Brokerage & Caching] Redis[(Redis Pub/Sub & KV Cache)] end subgraph Async_Worker [Asynchronous Background Engine] Inngest[Inngest Serverless Event Queue] Inngest_Cron[Inngest Weekly CRON Scheduler] end subgraph Database_Layer [Data Persistence] DB[(PostgreSQL - Neon Serverless)] Alembic[Alembic Database Migrations] end subgraph AI_Engine [Autonomous Multi-Agent Layer] LG[LangGraph State Machines] NotesAgent[Notes Agent: Planner-Research-Evaluator-Improver] IndustryAgent[Career Intelligence Agent] InterviewAgent[Mock Interview Agent] AssignmentAgent[Assignment Architect Agent] LLM[Google Gemini 2.5 Flash] Tavily[Tavily Search Engine] end subgraph External_Integrations [Third-Party Services] RP[Razorpay Checkout] CL[Cloudinary Asset CDN] end Web <-->|HttpOnly Cookies / REST API| FA Web <-->|SSE Progressive AI Stream| SSE_Stream Android <-->|Bearer Token / REST API| FA Web <-->|OAuth2 PKCE Flow| OAuth_Endpoint Android <-->|OAuth2 PKCE Flow| OAuth_Endpoint OAuth_Endpoint --> PKCE_Val OAuth_Endpoint --> Cookie_Mgr OAuth_Endpoint --> Token_Family Web <-->|Full-Duplex WebSockets| WS_Manager FA --> RL FA --> Teacher_Guard Teacher_Guard <-->|Verify Group Ownership| DB WS_Manager <--> Redis FA <--> DB FA <--> Redis FA <--> RP FA <--> CL FA -->|Dispatch Event `assignment/question.generate`| Inngest FA -->|Dispatch Event `interview/prep.create`| Inngest FA -->|Dispatch Event `student/industry.generate`| Inngest Inngest_Cron -->|Trigger Weekly Refresh `0 0 * * 0`| Inngest Inngest -->|Execute Steps & Write| DB Inngest -->|Invalidate Stale Keys| Redis Inngest <-->|Execute Multi-Step Agents| LG LG --> NotesAgent LG --> IndustryAgent LG --> InterviewAgent LG --> AssignmentAgent LG <-->|Prompt Synthesis & Reasoning| LLM LG <-->|Web Context Retrieval| Tavily ``` --- ## ⚡ Comprehensive Deep-Dive: Core System Features ### 🔐 1. Custom OAuth 2.0 Authorization Server (PKCE) ClassBuddy operates as an independent, standalone **RFC 7636 compliant OAuth 2.0 Authorization Server** with zero reliance on paid external providers (e.g., Clerk, Auth0). * **Proof Key for Code Exchange (PKCE)**: Utilizes `S256` code challenges and verifiers, safeguarding against authorization code interception attacks. * **Dual Client Transport Architecture**: * **Web Client (`classbuddy-web`)**: Implements strict `HttpOnly`, `SameSite=Lax/Strict`, `Secure` cookies (`access_token`, `refresh_token`), immunizing the browser from XSS token extraction. * **Android Mobile Client (`classbuddy-android`)**: Interacts via standard `Authorization: Bearer ` headers and JSON payloads. * **Token Rotation & Family Revocation**: Employs automated refresh token rotation. If an expired or already-consumed refresh token is replayed, the system instantly revokes the entire token family, neutralizing token hijackers. * **OIDC Endpoints**: * `POST /api/v1/oauth/authorize/login`: Validates credentials and yields single-use PKCE authorization codes. * `POST /api/v1/oauth/token`: Exchanges authorization codes or refresh tokens for active sessions. * `POST /api/v1/oauth/revoke`: Revokes refresh tokens and clears client cookies. * `GET /api/v1/oauth/userinfo`: Delivers cryptographically verified user claims. --- ### ⚙️ 2. Event-Driven Background Engine & CRON Schedulers (Inngest) To prevent server thread starvation during heavy AI and database operations, ClassBuddy integrates **Inngest** as an asynchronous serverless background execution engine. #### A. Asynchronous Assignment Question Synthesis (`fn_id: generate-assignment-questions`) * **Event Trigger**: `assignment/question.generate` dispatched upon teacher request. * **Step 1 (`ai-generate-assignment-questions`)**: Asynchronously executes `assignment_graph` with Gemini 2.5 Flash, extracting structured questions in JSON format. * **Step 2 (`db-update-assignment-questions`)**: Idempotently commits `AssignmentQuestion` records to PostgreSQL and resets `assignment.is_generating = False`. * **Resilient Fallback (`reset-generating-state-on-error`)**: On unexpected LLM or DB failures, Inngest triggers an automated step to reset `is_generating` to `False`, preventing UI hang. #### B. Mock Interview Preparation Generator (`fn_id: generate-interview-questions`) * **Event Trigger**: `interview/prep.create` triggered by student submission. * **Step 1 (`ai-generate-questions`)**: Calls `interview_graph` to produce dynamic, role-specific technical questions. * **Step 2 (`db-update-questions`)**: Commits the questions to the database and marks `InterviewPrep.status = Status.COMPLETED`. * **Step 3 (`db-update-error`)**: Fallback error handler sets status to `Status.ERROR` if generation or validation fails. #### C. Student Career Intelligence & Weekly Cron Engine (`fn_id: generate-student-industry-insight`) * **Dual Trigger Strategy**: 1. **User-Invoked Event**: `student/industry.generate` for immediate on-demand profile generation. 2. **CRON Scheduler**: `inngest.TriggerCron(cron="0 0 * * 0")` runs every **Sunday at midnight UTC** to refresh insights for all enrolled students. * **Step Execution Pipeline**: * `fetch-refresh-targets`: Queries all eligible student profiles across PostgreSQL. * `ai-research-{user_id}`: Runs `industry_graph` to analyze emerging market trends and required skills. * `db-sync-{user_id}`: Persists the updated skill matrices into the `StudentInsight` entity. * `clear-cache-{user_id}`: Automatically purges stale cache keys in Redis (`student_insights:{user_id}`) to ensure instant read consistency. ```mermaid sequenceDiagram autonumber actor User as Student / Sunday CRON participant Client as React Client participant API as FastAPI Backend participant Inngest as Inngest Event Engine participant LG as LangGraph AI Agent participant DB as PostgreSQL (Neon) participant Redis as Redis Cache User->>Client: Request Industry Insights / Cron Trigger Client->>API: POST /api/v1/studentInsight/generate API->>Inngest: Send Event `student/industry.generate` API-->>Client: 202 Accepted (Instant Non-Blocking Response) activate Inngest Inngest->>LG: Step 1: Execute `ai-research-{user_id}` LG-->>Inngest: Skill Matrix, Trends & Career Trajectory JSON Inngest->>DB: Step 2: Step `db-sync-{user_id}` (Upsert Entity) DB-->>Inngest: Commit Verified Inngest->>Redis: Step 3: Step `clear-cache-{user_id}` (Purge Cache) Redis-->>Inngest: Cache Invalidated deactivate Inngest Client->>API: GET /api/v1/studentInsight/ API->>DB: Read Fresh Database State DB-->>API: Up-to-date Record API-->>Client: Render Interactive Radar & Progression Charts ``` --- ### 🤖 3. Autonomous Multi-Agent AI System (LangGraph) Rather than relying on basic single-turn prompts, ClassBuddy uses stateful, cyclic multi-agent graphs built on **LangGraph** with integrated critique-and-refine loops: * **Cyclic Architecture**: `Planner` ➔ `Research` ➔ `Generator` ➔ `Evaluator` ➔ `Improver` ➔ `Saver` * **Planner**: Deconstructs syllabus topics into logical pedagogical units. * **Research**: Queries the Tavily Search API for up-to-date facts and verified external citations. * **Generator**: Drafts extensive Markdown notes with formulas and code examples. * **Evaluator**: Critiques the generated draft against clarity, depth, and academic rubrics. * **Improver**: Iteratively rewrites weak sections identified by the Evaluator before finalizing. * **Saver**: Commits the clean Markdown document into PostgreSQL. * **AI Evaluation Engine (`ai_evaluator.py`)**: Grades student code submissions and free-text assignments, outputting line-by-line feedback and rubric scoring. * **Progressive Token Streaming (`/api/v1/ai-stream`)**: Utilizes Server-Sent Events (SSE) paired with a custom `useAIStream` React hook to render LLM responses progressively with zero perceptual latency. ```mermaid sequenceDiagram autonumber actor Teacher participant Client as React Client (Vite 7) participant API as FastAPI Gateway participant LG as LangGraph State Graph participant Tavily as Tavily Web Search participant LLM as Gemini 2.5 Flash participant DB as PostgreSQL (Neon) Teacher->>Client: Request Notes (e.g. "Distributed Raft Consensus") Client->>API: POST /api/v1/notes (Topic & Parameters) API->>LG: ainvoke(state) activate LG LG->>LG: Node 1: Planner (Deconstruct Outline) LG->>Tavily: Node 2: Research (Fetch Live Web Context) Tavily-->>LG: Search Results & References LG->>LLM: Node 3: Generator (Draft Initial Markdown) LLM-->>LG: Initial Document Draft LG->>LLM: Node 4: Evaluator (Grade Depth & Accuracy) LLM-->>LG: Critique & Improvement Suggestions LG->>LLM: Node 5: Improver (Refine & Polish Draft) LLM-->>LG: Verified Study Guide LG->>DB: Node 6: Saver (Persist Markdown & Metadata) deactivate LG API-->>Client: 201 Created (Complete Markdown Document) Client->>Teacher: Render in Rich MD Editor & Previewer ``` --- ### 💬 4. Distributed Real-Time Communication Mesh (WebSockets + Redis Pub/Sub) * **High-Concurrency WebSocket Gateway**: Custom connection manager handling active student and teacher connections per classroom group (`groupMessage.py`). * **Redis Pub/Sub Distribution**: Enables horizontal scaling across multiple container instances; messages published on any node are instantly broadcast across the entire cluster. * **Data Reliability & History**: Every message frame is asynchronously persisted to PostgreSQL before broadcasting, with cursor-based infinite scroll loading on the frontend. ```mermaid sequenceDiagram autonumber actor Student participant Client1 as Student Client participant WS1 as WebSocket Server (Pod 1) participant Redis as Redis Pub/Sub Bus participant WS2 as WebSocket Server (Pod 2) participant Client2 as Teacher Client participant DB as PostgreSQL (Neon) Student->>Client1: Type Message ("When is Quiz 2?") Client1->>WS1: WebSocket Frame: SEND_MESSAGE WS1->>DB: Asynchronously Persist to PostgreSQL WS1->>Redis: PUBLISH channel:group_{id} {message_payload} Redis-->>WS1: Fan-out to Local Connected Sockets Redis-->>WS2: Fan-out to Remote Connected Sockets WS2->>Client2: WebSocket Frame: RECEIVE_MESSAGE Client2->>Client2: Optimistic UI Update & Sound Ping ``` --- ### 🏫 5. Teacher Group Onboarding & Access Control * **Onboarding Guard (`require_teacher_group`)**: Strict backend dependency enforcing group creation before accessing teacher tools. Restricted calls return HTTP 403: ```json { "detail": "Teacher must create a group before accessing this feature.", "code": "TEACHER_GROUP_REQUIRED" } ``` * **Status Endpoint**: `GET /api/v1/teacher/group-status` returns `{"has_group": bool, "group_count": int}` to conditionally render onboarding banners vs. active dashboards. * **Single Group Policy**: Enforces a strict 1-group limit per teacher account (`400 Bad Request` on duplicate creation). --- ### 💰 6. Native Monetization & Tier Management (Razorpay) * **Tier Management**: Teachers can configure up to 3 subscription tiers per classroom group with customizable pricing. * **End-to-End Payment Flow**: Integrated with Razorpay APIs supporting automated order creation, cryptographic webhook validation (`X-Razorpay-Signature`), and automatic membership activation. * **Revenue Telemetry**: Teacher dashboards feature real-time charts tracking gross volume, recurring subscribers, renewal rates, and payment logs. --- ### 📁 7. Centralized Media & Document Management (Cloudinary) * Unified upload pipeline (`docsupload.py`) supporting lecture slides, PDFs, code snippets, and student submissions via the Cloudinary Python SDK. * Provides authenticated asset URLs, thumbnail generation, and bandwidth-optimized CDN delivery. --- ### 📊 8. Insight Dashboards & Career Intelligence * **Teacher Analytics**: High-level views of assignment completion rates, student grade distributions, and revenue metrics. * **Student Career Hub**: Visual radar charts depicting skill mastery, weekly performance reviews, and AI-curated technology learning paths. --- ## 💡 Engineering Challenges & Solutions | Technical Challenge | Root Cause | Engineering Solution | Measurable Impact | | :--- | :--- | :--- | :--- | | **LLM Hallucinations in Educational Guides** | Single-turn prompts lack factual grounding and formatting consistency | Designed a 6-node LangGraph cyclic graph (Planner ➔ Research ➔ Generator ➔ Evaluator ➔ Improver ➔ Saver) with Tavily web grounding | 100% cited references, eliminated shallow content, and ensured structured Markdown | | **High Latency & HTTP Thread Starvation** | AI generation and analytics computation take 5–15 seconds, blocking server threads | Migrated all heavy workloads to Inngest background event workers with step-level memoization | Reduced transactional API response time to `< 120ms` | | **Weekly Data Staleness for Students** | Students need updated market and skill insights without manual button clicks | Configured an Inngest Cron trigger (`0 0 * * 0`) that runs every Sunday at midnight and purges Redis cache | Automated zero-touch updates for 100% of active student profiles | | **WebSocket Split-Brain across Server Pods** | Traditional in-memory socket lists only broadcast to clients on the same physical server | Implemented a Redis Pub/Sub message broker syncing channels across all running FastAPI instances | Sub-50ms message delivery across multi-pod cluster deployments | | **Token Theft & Security Across Web & Mobile** | Storing JWTs in browser localStorage leaves applications vulnerable to XSS | Architected a custom OAuth 2.0 PKCE server using HttpOnly Strict cookies for web and Bearer tokens for mobile | Neutralized XSS token theft and automated token-family replay revocation |

ClassBuddy

Built with