The World Is
Your Textbook

Gemma 4 Integration

The intelligence behind reallearn is Gemma 4 26B — chosen not because it's large, but because it follows instructions with precision, thinks in eight languages natively, and shapes its output into the exact structure learning demands.

Structured prompting meets a resilient post-processing pipeline. The model doesn't freestyle — it composes within a strict schema, and when it stumbles, the validation layer catches what falls.

What reallearn Is

A guided-learning platform for students who need more than answers — they need understanding.

It serves the learner who struggles with difficult topics, the one alienated by language, the one who reads but doesn't retain, the one who feels theory has nothing to do with the world they inhabit. reallearn was built for all of them.

The Problem We Solve

The gap isn't in access to information — it's in the architecture of understanding.

Traditional AI delivers one-shot answers: shallow, mismatched to the learner's level, detached from current reality, and forgotten within minutes. When a student asks "Why does the rupee depreciate?", a single paragraph about exchange rates teaches nothing that endures. The words arrive, but the understanding doesn't.

Students don't need more content. They need guided progression that respects their level. They need active recall that forces comprehension. They need real-world relevance that makes knowledge feel alive. That's the gap reallearn was built to close — not with more information, but with better architecture.

End-to-End Learning Flow

Every reallearn session follows a carefully orchestrated pipeline — from raw curiosity to validated understanding. This is the journey a question takes:

1. Ask. A learner enters a question — anything that sparks curiosity. There are no wrong questions.
2. Configure. The learner selects their language and depth. reallearn meets them where they are.
3. Request. The frontend calls /api/generate-lesson — the engine awakens.
4. Ground. The backend fetches real-world context — current events, recent developments, live data. Theory meets today.
5. Generate. Gemma 4 composes a structured 3-stage journey, calibrated precisely to level and language.
6. Validate. The backend runs a 5-stage resilience pipeline — if the model stumbles, the repair layer catches it.
7. Render. The frontend presents all 3 stages, sources, and quizzes — a learning experience, not a wall of text.
8. Gate. Each quiz must be passed to unlock the next stage. Comprehension is not assumed — it's verified.
9. Continue. The learner completes takeaways and loops deeper. Every answer opens a door to the next question.

Feature Deep Dive

Nothing is decorative. Everything is deliberate. Every feature closes a specific gap in how learners actually absorb, retain, and apply knowledge.

• 3-Part Unlockable Journey — Foundation → Mechanism → Real World Now. An arc from "what is it?" to "why does it matter today?"
• Quiz-Gated Progression — 2 MCQs per stage, 4 options each. You don't advance until understanding is demonstrated. Active recall, in its purest form.
• 8-Language Native Generation — English, Hindi, Gujarati, Tamil, Bengali, Marathi, Telugu, Kannada. Not translated — natively conceived in the learner's own language.
• Adaptive Depth Calibration — Three levels with distinct vocabulary, complexity, and conceptual scaffolding. The lesson reshapes itself around the learner.
• Real-World Context Integration — Serper-powered current event anchoring turns abstract theory into living knowledge that breathes with the present.
• SSE Streaming with Heartbeat — Real-time server-sent events with keep-alive pings. The learner sees progress unfolding, not a blank screen.
• Output Resilience Layer — 5-stage JSON repair and strict validation. The learner never sees a broken experience — even when the model does.
• Follow-Up Learning Loop — Every answer opens a door. Learners continue their journey iteratively, building depth with each question.
• Session-Persisted State — Progress survives refreshes. The learning journey respects the learner's time, attention, and investment.

Real-World Impact

reallearn was designed around real frustrations — not theoretical problems, but the lived barriers that millions of learners face every day. Each feature maps directly to a human need:

Tech Stack

Chosen not for novelty, but for reliability at every layer of the learning experience.

Architecture & Deployment

A clean two-service architecture — each optimized for its domain, deployed on infrastructure matched to its purpose:

• frontend/ → Next.js on Vercel — edge-optimized, globally distributed, instant cold starts.
• backend/ → Express API on Render — persistent compute for AI inference, streaming, and validation.
• Primary endpoint: POST /api/generate-lesson — the core learning engine.
• Health endpoint: GET /health — uptime monitoring and readiness checks.

API Behavior & SSE Streaming

Server-Sent Events stream progress in real-time, keeping learners informed and engaged throughout generation:

Project Structure

A clean, purposeful directory — concerns separated, intent clear:

reallearn/
├── frontend/         # Next.js app (UI, state, client flow)
├── backend/          # Express API, AI calls, validation, context fetch
└── README.md

Environment Variables

Every knob is exposed. Operators have full control over model parameters, retry behavior, circuit breaking, and streaming:

Frontend

• NEXT_PUBLIC_BACKEND_URL — Render backend URL (e.g. https://<app>.onrender.com)
• NEXT_PUBLIC_STREAM_IDLE_TIMEOUT_MS — SSE idle timeout (default: 120000ms)

Backend — Core

• GEMMA_API_KEY — Gemini API key for Gemma 4 access
• GEMMA_MODEL — Model identifier (default: gemma-4-26b-a4b-it)
• SERPER_API_KEY — Serper API key for real-world context enrichment
• FRONTEND_ORIGIN — Allowed CORS origin (e.g. https://<app>.vercel.app)
• PORT — Server port (default: 10000 on Render)

Backend — Retry & Circuit Breaking

• GEMMA_MAX_RETRIES — Max retry attempts (default: 2)
• GEMMA_RETRY_DELAY_MS — Initial retry delay (default: 700ms)
• GEMMA_MAX_RETRY_DELAY_MS — Retry delay cap (default: 5000ms)
• GEMMA_TIMEOUT_CIRCUIT_FAILURE_THRESHOLD — Failures before circuit opens (default: 5)
• GEMMA_TIMEOUT_CIRCUIT_COOLDOWN_MS — Circuit cooldown period (default: 60000ms)

Backend — Operational

• MAX_CONCURRENT_LESSON_REQUESTS — Concurrency limit (default: 3)
• LESSON_FAILURE_ALERT_THRESHOLD — Failure count for alerting (default: 5)
• SSE_HEARTBEAT_INTERVAL_MS — Heartbeat interval (default: 15000ms, capped at 55000ms)

Local Development

Two terminals, two commands, and the full learning experience is yours to explore:

# Terminal 1 — Start the backend
cd backend
npm install
npm start

# Terminal 2 — Start the frontend
cd frontend
npm install
npm run dev

Validation & Quality Checks

Run these before every deployment — quality is not optional:

cd frontend
npm run lint      # Catch lint errors and style violations
npm run build     # Verify production build succeeds

Roadmap & Vision

The vision extends far beyond individual lessons — toward a world where every learner has a patient, precise, and personally calibrated guide for any topic they dare to explore.

License

Open source under the MIT License — because the tools for better learning should belong to everyone.