Analytics dashboard of faculty
Gradebook view
Ai - Twin chat interface
student course page
Login page
Student dashboard

Lumina — AI Classroom Twin

Inspiration

Learning often stops when class ends. Students may remember a topic but forget the explanation, examples, and reasoning that made it understandable. At the same time, teachers rarely get a clear, privacy-conscious view of which concepts are causing confusion outside the classroom.

We built Lumina to preserve the continuity of teaching. Instead of replacing a teacher with a generic chatbot, Lumina creates an AI Classroom Twin: an assistant grounded in a course's uploaded lectures and materials, capable of explaining concepts in a teacher-informed style while letting students choose the format that helps them learn best.

Our core principle is:

Course knowledge determines what the AI says; the teacher profile determines how it says it.

This creates a continuous feedback loop:

Teacher uploads lectures and materials
            ↓
Course knowledge base and teacher profile are built
            ↓
Students ask grounded course questions
            ↓
Anonymous doubt patterns reach the faculty dashboard
            ↓
Teachers improve future instruction

What We Built

Lumina is a role-based AI learning platform for faculty and students.

Faculty can create courses and upload lecture recordings, slides, PDFs, and supporting materials. The backend processes these materials asynchronously by transcribing lecture media, extracting concepts, creating course knowledge records, and building a versioned teacher profile.

Students can ask the AI Twin questions specific to their course. The system retrieves relevant evidence only from that course, reranks it, checks whether enough evidence exists, and generates a cited response. Students can choose explanation modes such as:

Teacher style
Simple explanation
Step-by-step explanation
Visual or structured explanation

The faculty dashboard converts successful, grounded student questions into anonymous doubt analytics. It shows frequently confusing concepts, representative questions, explanation preferences, and lecture-level doubt patterns.

Lumina also provides attention alerts based on attendance and homework signals, helping faculty identify students who may benefit from a supportive check-in.

How We Built It

We built Lumina as two connected layers:

A Next.js + TypeScript frontend for faculty and student dashboards.
A FastAPI + PostgreSQL backend using SQLAlchemy, Alembic migrations, JWT authentication, and role-based access control.

The content-ingestion pipeline supports two paths:

Lecture + slides: slide concepts are matched with relevant transcript windows to create hybrid knowledge records.
Lecture only: the transcript is segmented into concept-level knowledge records.

Each record contains metadata such as course, lecture, concept, source type, and timestamps. This supports course-isolated retrieval and enables citations that link answers back to lecture content.

For the AI layer, we created provider abstractions that support Google Gemini and Hugging Face services, while deterministic local providers make development and testing reliable.

Before the AI generates an answer, Lumina performs:

Course-access validation
Guardrail and intent checks
Course-specific retrieval
Reranking of retrieved content
Retrieval-quality validation
Teacher-profile retrieval for style
Grounded generation with citations

If the system does not find enough reliable evidence, it does not invent an answer. Instead, it tells the student that the uploaded course material does not contain enough context.

Teacher Profile and Grounded AI

A central design decision was to keep teaching style separate from factual knowledge.

Course Knowledge Base: what was taught
Teacher Profile: how the teacher usually explains it

The teacher profile combines measurable signals such as pacing, sentence structure, readability, and question frequency with qualitative traits such as tone, analogy use, and explanation patterns.

The profile affects presentation only. It never becomes a factual source. This prevents the AI from sounding like a teacher while inventing unsupported classroom content.

Attention Alerts

Lumina uses transparent rules to estimate when a student may need support. The score is capped at 100:

$$ \text{Attention Score} = \min(100,\; A + M + L) $$

where:

(A) represents low-attendance signals,
(M) represents missing homework,
(L) represents repeated late submissions.

This score is not meant to judge students automatically. It is a prompt for teachers to review the context and decide whether a human conversation or intervention is appropriate.

Challenges We Faced

The biggest challenge was preventing a teacher-style AI from sounding convincing while being wrong. We solved this by separating style from factual grounding, enforcing course-level retrieval, applying guardrails, reranking evidence, attaching citations, and blocking generation when the retrieval-quality gate finds weak evidence.

Content ingestion was another challenge. Lecture recordings, audio files, slides, and PDFs vary widely in structure and quality. We built asynchronous processing states, video-to-audio preparation, slide parsing, fallback processing paths, idempotency checks, and reprocessing support when slides are uploaded after a lecture.

Privacy was equally important. Doubt analytics include only successful, grounded educational interactions and aggregate them by concept. Off-topic, weak-evidence, and flagged queries are excluded from faculty doubt analytics.

A current deployment challenge is handling large lecture and video files. Vercel is well suited for deploying our Next.js frontend, but it is not intended to be the primary destination for large media uploads and long-running video processing. In our current deployment flow, files need to be less than approximately 4.5 MB to avoid Vercel request-body/upload limitations. This makes it difficult to upload full lecture recordings or high-quality videos directly through the Vercel-hosted frontend.

Another limitation is the free Gemini API quota. In our current setup, it supports only around 20 responses, which is not enough for sustained student usage, repeated testing, or a full classroom deployment. This makes efficient retrieval, caching, deterministic fallbacks, and careful API usage essential.

Our deployment architecture therefore separates responsibilities:

Vercel: frontend hosting
FastAPI backend: authentication, uploads, AI processing, and APIs
PostgreSQL: persistent application data
Future object storage: large lecture, video, and media files

This separation will allow Lumina to scale media handling without treating the frontend deployment platform as a video-processing service.

What We Learned

We learned that educational AI needs more than a strong language model. It needs boundaries, traceability, privacy controls, and a product design that respects the teacher's role.

We also learned that human-designed system architecture is essential. The language model is only one component. The surrounding architecture decides how safely and reliably it behaves. Course isolation, retrieval gates, citations, teacher-profile separation, privacy filters, asynchronous jobs, and analytics rules are what turn a general-purpose model into a useful educational system.

Harness engineering was especially important for us. By harness engineering, we mean designing the workflows around the model: prompts, tools, retrieval, guardrails, fallbacks, quality checks, provider abstractions, and feedback loops. A strong model without a strong harness can still produce unreliable outcomes. A carefully designed harness ensures that the model receives the right context, uses the right evidence, and responds within clear educational boundaries.

We also learned that personalization should preserve student choice. A student may benefit from a familiar teacher-style explanation, but should also be able to switch to a simpler, visual, or step-by-step explanation without changing the underlying facts.

Finally, we learned the value of modular engineering. Separating routers, services, repositories, models, schemas, AI providers, content extraction, and teacher-profile logic made complex workflows easier to test and evolve. Our backend test suite passes all 55 tests, covering core application behavior, AI Twin wiring, content extraction, upload processing, teacher profiles, providers, and analytics.