Anshid

Teachling

← Back to Projects

1. Problem Statement

Most study apps test whether you remember the answer. Teachling tests whether you can explain it. The distinction matters: you can recognize a correct answer without understanding it, but you cannot explain a concept without genuinely grasping it.

The app is built around the Feynman Technique — a study method that forces you to expose gaps in your knowledge by trying to explain a concept simply:

  1. Pick a concept you want to learn.
  2. Explain it in plain language, as if to a child.
  3. Identify where your explanation breaks down.
  4. Go back to the material and fix those gaps.
  5. Repeat until the explanation is complete and simple.

Teachling automates steps 2–4 with AI.

2. The Three Characters

Character Role
Pip 🐣 The novice AI student you teach. Asks follow-up questions, expresses confusion when your explanation is vague, and catches misconceptions. Drives the understanding score.
Sage 🦉 The expert tutor — private to you (Pip never sees this channel). Ask Sage when you’re stuck, then return to teaching Pip. Steps in automatically when you say something factually wrong.
You 👤 The teacher/learner. Goal: get Pip’s understanding score from 0 to 100.

3. How It Works

  1. Upload a PDF, paste lecture notes, or paste any text.
  2. The AI reads the material and generates a study guide.
  3. Pip greets you and asks its first question.
  4. You explain concepts in your own words (paste is disabled on the Pip tab — no copying explanations).
  5. Pip asks follow-ups and shows visible confusion where your explanation is vague.
  6. An understanding score (0–100) updates after each turn.
  7. If you state something factually wrong, Sage steps in with a brief correction, then you re-teach Pip.
  8. Switch to the Sage tab anytime to ask the expert privately.
  9. Reach 100 → Pip graduates 🎓.

4. System Architecture

graph TD A[Browser / Android App] -->|HTTPS| B[React SPA\nFirebase Hosting] B -->|REST + JWT| C[Express API\nCloud Run] B -->|Auth SDK| D[Supabase Auth] C -->|Service Role| E[Supabase\nPostgreSQL] C -->|LLM calls with\nfallback chain| F[Vertex AI\nGemini Flash] C -->|Payments| G[Razorpay]

The API runs on Google Cloud Run (serverless containers, pay-per-request). The frontend is a React SPA deployed to Firebase Hosting. Both live inside the same GCP project, sharing one billing account.

5. Tech Stack

Layer Technology
Frontend React 18 + TypeScript + Vite + Tailwind CSS
Backend Node.js + Express + TypeScript
Database Supabase (PostgreSQL)
Auth Supabase Auth — email/password + Google OAuth; PKCE deep-link flow on Android
AI / LLM Vertex AI Gemini Flash (primary) with a multi-provider fallback chain
Payments Razorpay (INR subscriptions + multi-currency one-time passes)
Web hosting Firebase Hosting
API hosting Google Cloud Run (asia-south1)
Mobile Capacitor (wraps the web app as a native Android app)

6. Key Engineering Decisions

Multi-provider LLM fallback chain. The complete() function in the API accepts a primary model and an ordered fallback list. If a provider returns a rate-limit error or times out, the next provider is tried silently. A teaching turn never hard-fails due to a single provider outage.

Structured output contract — reply vs. payload separated. Pip’s user-visible text is extracted from a raw <reply>…</reply> block; the grading payload (understanding delta, incorrect claim flag) is a separate one-line JSON. In an earlier version, the reply lived inside the JSON envelope — any serialization wobble caused the raw JSON to leak into the chat bubble. Separating the two surfaces made the output deterministic regardless of model formatting quirks.

RLS with zero policies. Supabase Row Level Security is enabled on every table, but no policies are defined. This means the anon/public key — the one that ships to the browser — can read zero rows from any table. All data access goes through the Express API using the service-role key, which bypasses RLS. The API enforces ownership itself (WHERE user_id = $me). This eliminates an entire class of client-side data-exposure bugs without needing to maintain a policy per table.

7. Current Status

  • Web app — live at teachling.web.app
  • Android — built (Capacitor); on the Play Store internal/closed testing track
  • Payments — Razorpay INR subscriptions (Pro / Pro Max, monthly + yearly) live; international one-time passes in local currency
  • B2B classroom layer — instructors can create classes, publish module assignments, run assessments, and view a student × module mastery dashboard; shipped and live
  • Consumer tiers — Free / Pro (₹99/mo) / Pro Max (₹449/mo) + yearly options

8. Visit the App

teachling.web.app →