Tutor and Professor
Tutor and Professor is a full-stack personal tutoring app for anyone who wants to study — a language, a school subject, or programming. It combines short lessons, quizzes, spaced repetition, AI-generated practice, text-to-speech, account controls, and study tools. Content is written for the age band on the profile, from a six-year-old to an adult, which is also what keeps the extra content rules in place when the learner is a minor.
The project was built as a practical engineering exercise: a real product surface, a typed frontend, a Python API, persistent data, AI integration, runtime backend routing, auth, tests, and deployment constraints.
Live Demo
- Frontend: https://tutorprofessor.vercel.app
- Backend model: the Next.js frontend and the FastAPI API both run on Vercel; the database is PostgreSQL on Supabase. Only the Kokoro voice service may still run on a local machine behind a tunnel, and the app falls back to browser speech when it is off. See
docs/deploy-vercel-supabase.md.
What This Project Demonstrates
- Full-stack product thinking: learner-facing lessons plus account and admin workflows.
- Typed React/Next.js frontend with reusable API client and runtime connection handling.
- FastAPI backend with SQLModel models, Pydantic schemas, auth, and domain services.
- AI workflows with validation, retry-safe behavior, and safeguards against malformed generated content.
- Spaced repetition and review flows for vocabulary, lesson questions, coding flashcards, and study topics.
- Local-first deployment using Vercel plus Cloudflare Tunnel, including recovery from stale tunnel URLs.
- Automated tests for backend services, AI output validation, UI state helpers, and deployment edge cases.
Core Features
Studying
- One study queue. "Iniciar estudos" builds a session — today's lesson first,
then what review is due, then the questions still owed — and drops straight
into the first card. The queue is stored, so "Continuar de onde parou" on
the home screen resumes the exact card you stopped at, after a reload, a
closed app, or a day later.
GET /api/study/session only reads: opening the
app never starts a session by itself.
- Nothing already mastered comes back. A question answered right twice, with
the last answer also right, retires. The same rule runs on both sides
(
services/study_queue_service.py and lib/question-queue.ts), and "Refazer
todas" is there for whoever wants the whole topic again.
- A guided first run.
/onboarding asks who is studying and which language,
then places the student with a five-question test instead of starting everyone
at level 1. The test needs no content and no AI, so it works in the account's
first minute.
- Objectives you can measure.
/objectives holds what the learner is working
towards, and under each one the list of what has to be studied to get there.
Checking an item moves a percentage of reach that is computed from that list
and nothing else — items carry a weight, so "ler um capítulo" and "terminar o
curso" do not count the same. Reaching 100% is logged as a milestone in the
daily feed, and unchecking an item takes the badge back, because the number
always describes the current list.
- A plan for the objective, not just a list. "Criar plano" drafts a strategy
for one goal: the biggest bottleneck, the priorities in order, what not to do
yet and the shortest path. The learner writes "sobre você" and may include a
summary of their recorded study, shown word for word before anything reaches
the AI. Nothing is stored until the draft is reviewed, and each accepted
priority becomes an ordinary objective, so the plan's percentage and its
"próximo passo" come from the same checklists. "Revisar plano" sends the
current progress back to the AI; a revision can reorder, add and archive, but
never removes finished work. Without an AI key, ready-made models
(
apps/api/content/plan-templates/) give the same flow for free.
- Objectives linked to what you study. Choose a discipline and one or more
curriculum topics or study-log subjects. "Analisar objetivo" compares the
objective with the selected study history, answers and reviews, then keeps an
AI estimate of what remains, knowledge gaps and an ordered action plan with
completion criteria. Choosing a subject selects its topics automatically;
bulk selection also works with search results, up to 60 linked topics.
The goal form links recorded studies without asking for manual task items;
objectives without a checklist show their AI study assessment directly.
Relevant history is read in full, including old records and long text, using
bounded batches and summary consolidation over resumable requests. Each
request makes at most one provider call with a 45-second timeout; a durable
snapshot retains validated checkpoints across connection failures and retries.
An expiring claim prevents overlapping steps, and the previous diagnosis is
preserved until every batch and the final assessment succeed. One job reserves
one platform credit and records usage once, so the last available credit can
finish its whole history. An
empty history shows insufficient evidence rather than an invented percentage.
The estimate stays separate from checklist progress; editing the goal or its
study links marks the previous analysis as outdated. Optional analysis after
creation saves the objective first, so a provider failure keeps it available
for another attempt.
Content That Works Without AI
- A curated English pack of 30 lessons × 8 phrases (levels 1–4, A1 to A2),
each phrase with a translation, an example sentence, and a word-by-word
breakdown. The source of truth is
scripts/english_core_pack_data.py; run
python scripts/build_english_core_pack.py to regenerate the seed files and
python scripts/init_db.py to load them.
- Review questions and four-option practice questions are derived from the
lesson itself (
services/offline_question_service.py) — deterministic, free,
and immediate. POST /api/study/questions/ensure fills an empty topic, and the
questions panel calls it before it would show an empty state.
POST /api/study/questions/prefetch tops a topic up after the response has
already been sent: free questions first, and a provider call only when a key
and credit are actually there. Nobody waits on a spinner for a question.
Account Area
- Account registration and login.
SIGNUP_MODE=manual (the default) holds a new account in the administrator's queue; SIGNUP_MODE=open lets a verified e-mail address in on its own.
- E-mail verification, forgotten-password reset, password change and sign-out-everywhere, all self-service. Both e-mail flows answer identically for an address that exists and one that does not, so they cannot be used to find out who has an account.
- Optional modules per account: the programming curriculum, flashcard decks and LeetCode trainer ship switched off and are turned on in the account area. The gate is one middleware over route families rather than a check repeated in thirty endpoints.
- Data rights without asking anybody:
GET /api/account/export downloads everything stored about the account, POST /api/account/delete erases it.
- Password policy enforced on both sides: the signup form shows a live strength meter and requirement checklist, and
services/password_policy.py applies the same rules on the API, so a direct HTTP call cannot skip them.
- Login has a brute-force brake: after
MAX_FAILED_LOGINS wrong passwords the account is locked for LOGIN_LOCK_MINUTES and answers 429 with Retry-After. The lock clears itself, and a successful login resets the counter.
- Passwords are stored as PBKDF2-HMAC-SHA256 with 600,000 iterations (OWASP's current floor) and a per-password random salt. The hash records its own iteration count, and an older 260,000-iteration hash is upgraded in place on the next successful login.
- Account dashboard for students, progress, settings, and AI provider configuration.
- Student profile management, including target language, age band and audio preferences.
- AI-powered lesson, question, book, and flashcard generation.
Admin Area
- Admin dashboard at
/admin with counters for the approval queue, approved accounts, recent signups, and AI authorizations.
- Account approval at
/admin/accounts: every signup waits in a queue and only reaches the app once approved. Rejecting an account drops its open sessions immediately, and a rejection can be reversed later.
- AI access is a second, independent switch: approving an account grants no AI, and revoking AI leaves the account working. Both are set from the same queue card.
- AI credits meter the administrator's own key at one credit per successful generation. A call the provider never answered is free, and an account using its own API key is never metered. Accounts can be topped up, zeroed, or marked unlimited.
- Per-account AI authorization at
/admin/users, plus the internal learning content editor at /admin/learn.
Plans and Billing
- Plans live in
apps/api/services/billing_service.py rather than in a table: a price changes through a reviewable deploy, not a row edited in production. An account with no subscription row is on the free plan, so signup creates nothing and the app runs with billing switched off.
- One
Entitlement decides everything: how many students a plan allows, and how much AI it includes. The AI allowance is credited into the balance the administrator already controlled, so there is one meter instead of two competing ones, and hand-granted credits are never taken away.
- A 14-day trial needs no payment gateway at all. Paying does, and says so plainly rather than pretending to have taken the money.
past_due keeps working: a card that failed this morning should not take a student's lesson away before the gateway has finished retrying.POST /api/billing/webhook verifies an HMAC signature over the raw body and ignores repeated deliveries by event id — the retry every gateway sends must not extend a period twice.- Every generation writes a usage line with an estimated cost in millionths of a currency unit, so "what did this account cost this month" has an answer. See
docs/saas-operacao.md.
Installable App (PWA)
- Installable on phone, tablet and desktop: web app manifest, maskable icons, and an
apple-touch-icon so iPhone and iPad get the real icon instead of a page thumbnail.
- Opens without browser chrome (
display: standalone), with both the standardised and the legacy apple-mobile-web-app-capable meta so iOS before 17 also goes full screen.
- A small service worker caches the app shell and immutable
/_next/static/ assets, and shows public/offline.html when a navigation fails with no network. It never touches the backend or any /api/ route, so the runtime backend URL is always read fresh.
- Icons are generated from the app's own brand mark:
python scripts/generate-pwa-icons.py.
Installing it
- iPhone / iPad: open the site in Safari (it must be Safari), tap Share, then "Adicionar a Tela de Início".
- Android / Chrome: the browser offers "Instalar app", or use the menu's "Adicionar à tela inicial".
- Desktop Chrome / Edge: the install icon appears at the right of the address bar.
Installation needs HTTPS, which the Vercel deployment already provides.
Study Modes
- Objectives with a weighted study checklist and a percentage of reach, summarised on the dashboard.
- Study plans that turn a goal into ordered objectives, drafted by AI or from ready-made models.
- General study dashboard with planning, notes, distractions, and pomodoro count.
- Diverse subject study mode for custom topics and AI-generated questions.
- Programming curriculum with subjects, topics, generated explanations, quizzes, and flashcards.
- Coding review and deck-style flashcard study with scheduling state.
- LeetCode-style method trainer.
Tech Stack
| Layer | Technology |
|---|
| Frontend | Next.js 15, React 19, TypeScript, Tailwind CSS |
| Backend | FastAPI, SQLModel, Pydantic, SQLAlchemy |
| Database | PostgreSQL: Supabase in production, local on port 5433 for development |
| Migrations | Alembic through database_bootstrap.py, which also keeps Supabase's public Data API locked out of the tables |
| AI | Configurable provider layer, Gemini as the default path |
| TTS | Kokoro-compatible service plus browser fallback; audio cached in a private Supabase Storage bucket |
| Deployment | Vercel for web and API (pdx1, next to the database), Docker/VPS path kept in docs/DEPLOY-VPS.md |
| Tests | Playwright E2E (TypeScript), Python unittest-style scripts, Node assertion scripts, TypeScript check |
Architecture
Browser (PWA)
|
| Next.js app on Vercel
v
FastAPI API on Vercel (serverless, pdx1)
|
+-- PostgreSQL on Supabase (RLS on, Data API roles revoked)
+-- Supabase Storage (private audio cache, signed URLs)
+-- AI generation services (Gemini by default)
+-- Kokoro TTS, reached through a tunnel, with browser fallback
+-- Review and study scheduling services
Key Design Decisions
- The browser only talks to our API. Supabase's public Data API is closed on every table (row level security with no policies plus revoked grants), so a leaked publishable key reads nothing.
- Runtime backend state: the frontend can still discover a backend URL at runtime, which is what the local and tunnel setups use.
- Safe connection fallback: read-only API calls can recover from stale saved backend URLs by refreshing the global runtime backend state.
- Token plus cookie auth: cookies support same-site local flows, while bearer tokens support cross-domain mobile usage.
- Validated AI writes: generated lessons, questions, topics, and flashcards are checked before being persisted so invalid or partial AI output does not corrupt study state.
- Bootstrap before serving: the backend validates and upgrades legacy database schemas before accepting traffic.
Repository Layout
english-kids-tutor/
apps/
api/ FastAPI backend
content/ Seed content, inside the deployable unit
lessons/ Seed lesson JSON
quizzes/ Seed quiz JSON
stories/ Story content
admin-learn/ Admin learning modules
web/ Next.js frontend
docs/ Architecture, setup, deployment notes
infra/cloudflare/ Cloudflare Tunnel config example
scripts/ Local automation and test scripts
docker-compose.yml Optional containerized services
Running Locally
Fast Path on Windows
From the repository root:
.\start-project.cmd
To start backend, frontend, and Cloudflare Tunnel together:
.\start-project.cmd -WithTunnel
For the deployed Vercel frontend plus local backend flow, use:
.\ativar-tudo.cmd
That script starts FastAPI, opens a Cloudflare Tunnel, and publishes the current backend URL so the Vercel frontend can find it.
The Windows launchers also ensure the local PostgreSQL container is running before the API starts.
Backend Manually
cd apps/api
python -m pip install -r requirements.txt
python database_bootstrap.py
python -m uvicorn main:app --host 0.0.0.0 --port 8001 --reload
Backend health check:
Invoke-WebRequest http://127.0.0.1:8001/health
Frontend Manually
cd apps/web
pnpm install
pnpm dev
Local URLs:
Local PostgreSQL
This project uses a dedicated local PostgreSQL instance on host port 5433.
That avoids collisions with another PostgreSQL server that may already be
running on the default 5432 port.
docker compose up db -d
python scripts/migrate_sqlite_to_postgres.py --postgres-url "postgresql://kids_tutor:[email protected]:5433/kids_tutor"
The migration script backs up apps/api/kids_tutor.sqlite, migrates from a
working copy, refuses to copy into a non-empty PostgreSQL database by default,
and verifies row counts before reporting success.
Runtime Backend Connection
The deployed frontend needs a reachable backend URL. There are two supported paths:
- Automatic: run
.\ativar-tudo.cmd, which publishes the current tunnel URL.
- Manual: open
/connect in the deployed frontend and paste the Cloudflare Tunnel URL.
Example:
https://tutorprofessor.vercel.app/connect
The app stores the backend URL per browser and can also read a shared runtime state from the Vercel API. This avoids redeploying the frontend every time a temporary Cloudflare URL changes.
Environment Variables
Backend
Create apps/api/.env or use the local secret flow documented in local.secrets.example.
APP_HOST=0.0.0.0
APP_PORT=8001
DATABASE_URL=postgresql://kids_tutor:[email protected]:5433/kids_tutor
CORS_ALLOWED_ORIGINS=http://localhost:3000,https://tutorprofessor.vercel.app,https://english-tutor-kid.vercel.app
SESSION_SECRET=change-me
GEMINI_API_KEY=your-key
GEMINI_MODEL=gemini-3.1-flash-lite
TTS_PROVIDER=kokoro
KOKORO_URL=http://127.0.0.1:8880/v1/audio/speech
PARENT_COOKIE_SECURE=true
PARENT_COOKIE_SAMESITE=none
# The single administrator: the account with this e-mail owns /admin and never
# waits in its own approval queue. ADMIN_PASSWORD_HASH is an optional recovery
# password so the administrator can sign in even if the stored one is lost.
[email protected]
ADMIN_PASSWORD_HASH=
# Brute-force brake on login. Defaults shown; the lock clears itself.
MAX_FAILED_LOGINS=5
LOGIN_LOCK_MINUTES=15
Creating the Administrator Account
ADMIN_EMAIL names the administrator, but the account itself still has to exist
in the database. Create it (or reset its password) with:
python scripts/create-admin-user.py --email [email protected]
The script prints the ADMIN_PASSWORD_HASH line to store in the environment.
Then sign in at /login with that e-mail and open /admin.
Frontend
For local development:
NEXT_PUBLIC_API_BASE_URL=http://localhost:8001
For the deployed flow, the runtime backend route can resolve the tunnel URL dynamically.
Testing and Verification
Browser E2E tests, protected Codegen, isolated test data and GitHub Actions are
documented in docs/testing.md. From apps/web, run
pnpm test:e2e:safety, pnpm test:e2e, or pnpm e2e:codegen to record a new flow.
Useful checks:
cd apps/web
pnpm exec tsc --noEmit
python scripts/test_language_ai_questions.py
python scripts/test_programming_ai_flashcards.py
python scripts/test_ai_flashcard_service.py
python scripts/test_admin_account_approval.py
python scripts/test_ai_credits.py
python scripts/test_password_security.py
python scripts/test_tenant_isolation.py
python scripts/test_objectives_progress.py
python scripts/test_study_plan.py
python scripts/test_objective_deletion_foreign_keys.py
python scripts/test_objective_study_analysis.py
python scripts/test_objective_full_history.py
python scripts/test_objective_analysis_jobs.py
python scripts/test_objective_job_deletion.py
python scripts/test_migration_0041_objective_workflow.py
python scripts/test_account_modules.py
python scripts/test_account_self_service.py
python scripts/test_billing_and_usage.py
test_tenant_isolation.py is the one to run after touching any route. Besides
driving two accounts against each other over HTTP, it audits every registered
route: a data route that does not resolve its tenant through a known helper, or
an /api/admin route that never reaches an admin check, turns it red. Adding an
endpoint that answers with whatever id it was handed fails the build instead of
shipping quietly.
node apps/web/scripts/test-api-offline-fallback.mjs
node apps/web/scripts/test-pwa-manifest-and-sw.mjs
node apps/web/scripts/test-runtime-backend-state.mjs
node apps/web/scripts/test-lesson-question-state.mjs
node apps/web/scripts/test-diverse-question-state.mjs
node apps/web/scripts/test-objectives-ui.mjs
node apps/web/scripts/test-objective-plan-ui.mjs
The test suite is a mix of service-level tests, API behavior checks, and lightweight frontend state tests. It focuses on high-risk areas: AI output validation, concurrent/stale generation flows, runtime backend selection, and review state consistency.
Engineering Highlights
- Runtime backend freshness: the app chooses the newest backend state when multiple storage sources disagree.
- Stale tunnel recovery: safe read-only frontend requests can retry against the latest global backend URL.
- Cross-domain auth support: token auth complements cookies for Vercel-to-tunnel and mobile browser scenarios.
- AI validation before persistence: generated batches are checked for count, identity, ownership, and schema before database writes.
- Atomic generation paths: invalid AI output should fail without partial database rows.
- Local database resilience: startup bootstrap handles legacy local schemas before serving requests.
- Honest UX states: loading, empty, offline, retry, and recovery states are part of the product flow.
Trade-offs and Current Limitations
- Vercel does not run migrations. Run
database_bootstrap.py against the Supabase session pooler before pushing code that needs a new one.
- Google sign-in is broken across the two
.vercel.app domains (the callback cookie lands on the API's domain); e-mail login is unaffected. A custom domain or a one-time code on the redirect fixes it.
- Only the Kokoro voice may still depend on a local machine and a tunnel; when it is unreachable the app uses browser speech.
- Some tests are script-based rather than a single unified test runner.
- No payment gateway is wired in. Plans, limits, trials, usage and the webhook all work; what is missing is the checkout call in
start_checkout and the credentials.
- Rate limiting counts in process memory, so the effective ceiling multiplies by the number of uvicorn workers. Fine for one worker, which is the current deployment; move it to a shared store before scaling out.
- The per-generation AI cost is an estimate until the provider layer reports token counts.
apps/api/main.py is one large module. The route audit in scripts/test_tenant_isolation.py keeps the security properties honest, but splitting it into routers is still owed.- The app has grown beyond the original English-only scope into a broader personal tutor, so naming and documentation are being updated accordingly.
Suggested Interview Walkthrough
If you are reviewing the project, start here:
- Open the live frontend and note the local-backend requirement.
- Read
apps/web/src/lib/api-config.ts and apps/web/src/lib/runtime-backend.ts for runtime backend resolution.
- Read
apps/api/main.py around auth, lessons, review, and AI generation routes.
- Inspect service modules under
apps/api/services/ for validation and domain logic.
- Run
pnpm exec tsc --noEmit and one or two scripts under scripts/ or apps/web/scripts/.
Documentation
TODO-SAAS.md: what is done and what is left to run this as a product.docs/analise-melhorias-funcionalidades.md: prioritized feature improvement analysis (Portuguese).docs/deploy-vercel-supabase.md: hosting the database on Supabase and the API on Vercel, and what changes when the request has a time limit.docs/saas-operacao.md: operating it for other people — configuration, plans, cost per account, logs, backups, data rights.docs/privacidade.md and docs/termos.md: privacy policy and terms drafts, written from what the software actually does and awaiting legal review.docs/architecture.md: broader architecture notes.docs/setup-local.md: local setup details.docs/cloudflare-tunnel.md: named tunnel setup.docs/vercel-deploy.md: Vercel deployment notes.guia.md: Portuguese guide for running Vercel frontend with local backend.
License
MIT
