An AI tutor that answers only from your teacher's textbook — at your measured level.
One system for the entire tutoring business: recurring schedules that generate themselves, payments both parties must confirm, homework graded by a vision model that shows every mistake — and an AI layer with boundaries, grounded in each teacher's own curriculum and each student's detected weak spots.
When a student quietly falls behind, nobody notices — until the exam.
The scattered-tools way
- WhatsApp for scheduling, spreadsheets for payments, memory for tracking who struggles with what.
- A cap on how many students one tutor can manage well — and no structured signal for parents.
- Generic chatbots that answer confidently from the whole internet — not from this class's curriculum.
The Hossaty way
- One closed loop: operations (schedules, payments, groups, ratings) feeding an AI layer that is grounded, scoped and metered.
- Every graded homework makes the next tutoring answer smarter — weaknesses are remembered across sessions.
- AI cost metered per teacher, monthly quota, hard-blocked free tier — never an open-ended liability.
The design premise: AI is a tutor's assistant, never a replacement. It does the grading drudgery, the reminder logistics and the pattern-spotting — and leaves the teaching to the teacher.
Six pipelines — not a thin OpenAI wrapper
Every AI feature has a defined pipeline with explicit failure states. If retrieval fails, the assistant degrades gracefully to scoped chat — it never silently pretends to know the book.
Curriculum-scoped answers
The assistant is not an open chatbot. Before every answer, four independent signals assemble the prompt: the teacher's own textbook chunks, the student's measured level, their detected weaknesses, and conversation memory. Off-curriculum questions are gently redirected.
chatBuilder · 4 signalsHomework grading by vision
A student photographs handwritten homework; a vision model returns a structured per-mistake breakdown — problem number, the issue, the correction — and points the student back to specific textbook pages. Student and teacher see the same review; the teacher can add a human comment or request re-evaluation.
gpt-4o-mini vision · JSON reviewWeakness-detection flywheel
After every rating below 6/10 and every homework with flagged mistakes, the topic is extracted and its occurrence count grows. The system remembers a student's struggles across sessions without a human re-entering them — every graded homework makes the next tutoring answer smarter.
weaknessDetector · the flywheelDocument ingestion (RAG)
A teacher uploads a PDF textbook → a background job extracts text, splits it into overlapping chunks respecting paragraph boundaries, embeds them, and stores them for cosine-similarity retrieval. Failure states are honest: a scanned PDF with no extractable text is marked failed with the reason — never a silent fake success.
pgvector · 69 chunks / 6 pages, liveProvider abstraction
All three AI calls — chat, embeddings, vision — route through a swappable provider interface. OpenAI is implemented; adding Anthropic or OpenRouter means implementing the same 3-method interface with zero route changes.
ai/providers.js · 3 methodsCost control, first-class
AI usage is metered per teacher via a monthly quota checked before every chat message and grading, reset automatically on the 1st. Free-tier teachers are blocked from AI features entirely rather than silently billing overages. The admin console shows per-teacher usage bars color-coded by consumption risk.
quota · monthly reset · admin barsFour signals assemble every answer
| Signal | Source | Effect on the answer |
|---|---|---|
| Curriculum grounding | Top-3 most similar chunks from that teacher's uploaded material (pgvector, scoped to the subject) | The assistant teaches the teacher's curriculum, cites the textbook, and stays inside it. |
| Measured level | The student's average rating, mapped to beginner / intermediate / advanced | A struggling 5/10 student gets step-by-step basics; a 9/10 student gets challenge. |
| Known weaknesses | Active weakness-detection records, explicitly injected | The assistant proactively revisits the exact topics the student historically fails. |
| Conversation memory | The last 3 turns | Coherent multi-turn tutoring. |
Built for the tutor, the student — and the operator
The tutor
- Onboarding that starts in WhatsApp, not a form — students don't need to pre-exist.
- Fixed weekly template → sessions auto-generate across a rolling 30-day horizon, timezone-safe, overlap-proof.
- Both no-show directions tracked — teacher absences as visible as student ones.
- 6-dimension ratings after each session feed the AI's level signal.
The student
- Next-session hero with countdown + weekly color-coded calendar.
- Homework by camera: upload → live 'grading…' → per-mistake review with textbook pages.
- Streaks, 7 auto-awarded achievements, group leaderboards with a podium and trend arrows.
- An AI tutor framed as 'stuck on a question?' — with real math rendering, never raw LaTeX.
The admin
- Live KPIs: tutors, students, sessions, monthly revenue, services health.
- AI usage & cost: per-teacher quota bars color-coded by consumption risk.
- Subscriptions + self-hosted license keys with caps and expiry.
- Full audit trail of every administrative action.
Grounded · personalized · cost-bounded
The pattern — an authority's curated source of truth, personalization from measured evidence, a graded artifact feeding a weakness loop, and metered cost — transfers to four researched domains:
Enterprise knowledge assistants
The field already arrived at Hossaty's core principle: ground the assistant in the organization's own documentation, because an ungrounded assistant that answers fluently and wrongly about internal policy is worse than none. What's rarely built: personalization by measured signal (onboarding tenure, role) and a weakness flywheel on repeated ticket topics — which policy area keeps generating confused tickets, before it becomes a compliance problem.
Field-service diagnostics
A technician photographs a damaged component; a vision model diagnoses it — Hossaty's grading pipeline with roles reversed: equipment against its manual instead of homework against a textbook. The rarely-built piece: grounding in that equipment line's manual and tracking which failure types a technician keeps encountering — a training-gap signal a maintenance manager doesn't currently get for free.
Compliance training & assessment
Vendors already market 'not a general chatbot — a retrieval-grounded assistant that only speaks from your controlled documents', with quiz questions tied to policy clauses. What Hossaty adds cleanly: the weakness flywheel as a continuous signal — if 40% of employees miss the same clause, that's an automatically maintained dashboard instead of a manual analysis before the next audit.
Patient education
Generic health content is a known weak point: a diabetic patient and a heart-failure patient need materially different material, tailored to individual health literacy. 'Measured level, not inferred' maps directly — a comprehension check becomes the level signal, the assistant stays grounded in that patient's actual care plan, and the weakness flywheel flags which parts of a discharge plan the patient keeps getting wrong — surfacing where a follow-up call is worth the time before a missed instruction becomes a readmission.
Production-hardened, honestly-failing
Security in layers
JWT with role claims, bcrypt, single-use activation tokens locked with FOR UPDATE; password policy enforced in code; Helmet HTTP hardening with strict CORS; parameterized queries everywhere; rate limits per route.
Every job writes why it failed
Five BullMQ workers with retry/backoff — document processing, vision grading, session generation, quota reset, reminders. A failed document says why it failed ('OCR not supported'); a completed horizon stays full via a nightly 02:00 UTC cron.
Payments built on trust
Either side logs a payment (cash / transfer / card); it starts pending, and only the other party can confirm or reject — the initiator is structurally forbidden from confirming their own entry. One rule that removes the most common tutor–parent dispute.
Supply chain, cleaned
Dependencies upgraded to clear every Dependabot alert — including a critical JWT-bypass CVE. Daily automated backups (DB dump + files + git bundle) with 30-day retention.
Bilingual by architecture
English default with one-click full Arabic RTL, persisted per user. Logical CSS properties throughout — sidebars, calendars, chat bubbles flip natively. New languages = one dictionary file.
Data model with intent
28 tables around a central enrollment relation: schedules, generated sessions, 6-dimension ratings, bidirectional payments, groups with competition settings, achievements, textbook chunks, weakness records, quotas, licenses, audit logs.
What's live, what's next
Core platform
LiveAuth, scheduling, sessions, payments, ratings, groups — the full non-AI foundation, production-hardened.
AI layer
LiveAll six pipelines: RAG indexing, vision grading, weakness flywheel, scoped chat, quotas, provider abstraction.
Gamification + frontend
Live7 auto-checked badges, competition engine, and role dashboards for tutor, student and admin — EN/AR.
Payments gateway + WhatsApp
NextRecurring plan billing on the existing ledger; Twilio templates pending activation. Multi-tenant self-hosted edition already modeled; a camera-first mobile app planned.
What would grounded-and-personalized look like in your field?
A specific authority's document as ground truth, a measurable individual profile, and a graded artifact worth learning from.