Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.tuturuuu.com/llms.txt

Use this file to discover all available pages before exploring further.

Tulearn lives in apps/tulearn and runs locally on port 7812. It is the learner-facing companion to the main Tuturuuu web platform: students and parents use Tulearn for lessons, practice, assignments, reports, marks, XP, streaks, and hearts, while teachers and admins continue to manage education data in apps/web.

​
Ownership model

Tulearn owns its email/password and email-code auth shell locally. Login, callback, logout, and session routes are implemented inside apps/tulearn. Auth metadata uses the tulearn client value, and web-style Supabase cookies are kept on the Tulearn app. Social auth providers still run on apps/web because OAuth provider callbacks are registered for tuturuuu.com. Tulearn social buttons redirect to the central web login with returnUrl=<Tulearn /verify-token URL> and provider=<provider>. After the web callback succeeds, apps/web generates a cross-app token for the tulearn app, redirects back to /verify-token, and Tulearn creates its own domain-scoped Supabase session through POST /api/auth/verify-app-token. Protected product data still belongs to the central platform. Tulearn calls apps/web APIs through @tuturuuu/internal-api, and the satellite app rewrites /api/v1/* to the central web app when no local Tulearn route exists. Tulearn also exposes a learner-focused AI Chat surface at /[wsId]/ai-chat. The UI stays inside apps/tulearn, while the chat stream uses the central apps/web /api/ai/* routes through the satellite rewrite so model routing, credits, logging, and chat persistence remain centralized.

​
Workspace access

Every Tulearn workspace API requires both:
  • the authenticated user has student access or an explicit active parent-student link; and
  • workspace_secrets.name = ENABLE_EDUCATION has a truthy value for that workspace.
The bootstrap route only returns eligible education workspaces and linked students: 
GET /api/v1/tulearn/bootstrap
Workspace-scoped learner routes use the normalized workspace id so aliases like personal do not diverge between selection and final reads. Parent access is explicit and read-only in v1. The Tulearn schema adds:
  • tulearn_parent_student_links for accepted parent to student links;
  • tulearn_parent_invites for invite-based parent linking;
  • admin-managed parent-link APIs under /api/v1/workspaces/[wsId]/tulearn/parent-links.
Parents can switch between linked students in Tulearn. Parent requests may read home, courses, assignments, reports, marks, and practice context for linked students, but mutation routes reject parent writes.

​
Gamification

Tulearn-owned gamification tables are separate from teacher-owned course data:
  • tulearn_gamification_events stores XP events with an idempotency key per workspace and learner.
  • tulearn_learner_state stores hearts, max hearts, total XP, streaks, freezes, selected workspace, and UI preferences.
Courses, modules, quiz sets, flashcards, assignments, monthly reports, and marks continue to reuse existing education and user-group tables.

​
Code organization

Tulearn learner pages keep the public apps/tulearn/src/components/learner-pages.tsx entrypoint as a thin barrel export. Route-level screens live under apps/tulearn/src/components/learner-pages/*, with shared page motion, loading, empty state, and section primitives in shared.tsx. Keep Tulearn learner files under 400 LOC and individual components under 200 LOC. When a screen grows, split reusable cards, rows, panels, and route-specific helpers into adjacent modules before final verification instead of letting learner-pages.tsx or any route screen become a monolith again. Language switching is handled inside Tulearn with next-intl localized navigation links. Keep English and Vietnamese strings in apps/tulearn/messages/en.json and apps/tulearn/messages/vi.json, then run bun i18n:sort.

​
Verification

After changing Tulearn schema, API, or UI code, run: 
bun sb:up
bun sb:typegen
bun i18n:sort
bun type-check:tulearn
bun check
Run focused route or component tests around parent read-only access, student-only writes, XP idempotency, assignment completion, marks, and reports when those behaviors change.

​
CI and deployment

Tulearn has dedicated Vercel workflows:
  • .github/workflows/vercel-preview-tulearn.yaml
  • .github/workflows/vercel-production-tulearn.yaml
Both workflows are registered in tuturuuu.ts and use the shared ci-check.yml switchboard. They require the standard Vercel secrets plus VERCEL_TULEARN_PROJECT_ID; production also uses the shared production Supabase secrets. apps/tulearn/vercel.json disables Vercel Git deployments and GitHub integration so preview and production deploys only happen through the CI workflows.