> ## 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.

# Learning Management System

> Role-aware teaching and learning at one canonical address.

## Product decision

Tuturuuu LMS uses `https://tuturuuu.com/lms` as its canonical entry.
One workspace can expose Teach, Learn, or both depending on existing
membership, teaching permissions, and learner access. Hiding a navigation
link does not grant or revoke access. Each page and mutation enforces its
existing authorization at the server. Invitations remain accessible to
their intended recipients through the existing verification and consent flow.

| Area | Audience | Destinations |
| - | - | - |
| Teach | Teachers and education administrators with workspace access | Dashboard, courses and modules, quiz authoring, timetable, lessons, attendance, grading, and reports |
| Learn | Learners with access to the selected workspace | Home, courses, practice, progress, and library |

The public entry links to both areas. The area dashboard resolves an eligible
workspace from the signed-in account.
Users with both roles can switch areas without reauthenticating. The Teach
dashboard surfaces work awaiting grading and links directly to courses,
quiz authoring, and the timetable. The Learn home prioritizes
resuming study and finding assigned work. The current education and learning
data models remain authoritative for both areas.

## E-learning roadmap

| Area | Planned experience |
| - | - |
| Classes | Manage sections, rosters, teachers and assistants, invitations and join codes, timetables, announcements, and attendance. |
| Lessons | Build courses, modules, and lessons with rich text, video, Drive files, and approved embeds. Save drafts, publish, and set prerequisites and release dates. Track completion per learner. |
| Assessments | Build reusable question banks with single and multiple choice, short answer, matching, and ordering. Evaluate code and math against grading and accessibility requirements. Support timed tests, randomized forms, automatic and manual grading, rubrics, and controlled results publication. |
| Assignments | Set due dates and late policies. Accept text and file submissions, preserve resubmission history, and bring feedback and grades into the class gradebook. |
| Motivation | Offer class-controlled XP, levels, streaks, badges, achievements, progress rings, and daily goals. Class leaderboards are optional and exclude learners who opt out. Celebrations respect reduced-motion preferences. |
| Learner workspace | Bring next-up lessons and assignments together with progress, practice, the library, and notifications. |
| Teacher workspace | Bring class activity, a grading inbox, and analytics together in the teaching dashboard. |

Start with navigation and next-up using existing Teach and Learn data. Add class
and lesson workflows on the shared education model, then extend assessment and
assignment delivery. Introduce motivation features as classes gain reliable
completion and grading events. Teachers choose which motivation features to
enable for each class. Rewards reflect recorded learning activity and have no
effect on academic grades.

Workspace managers control class enrollment and role assignment. Join codes
and invitations use explicit class scope, expiry, and the permitted enrollment
path. Learners see released content and their own eligible submissions and
grades. Practice, active tests, and published review each have a separate
response contract. Practice exposes feedback only for eligible submitted work.
Active tests carry prompts and the learner's saved responses. Graded test
review exposes results and answer keys only after submission and authorized
release. Grading uses the saved attempt and its question snapshot. Repeated
requests preserve a single submission and reward outcome.

Reuse Education Core and the existing Teach and Learn records. Extend the
shared model through reviewed migrations that preserve the enrollment,
snapshot, and idempotency boundaries. Web uses the existing satellite session.
Shared APIs carry the same role, release, and workspace rules for later mobile
clients. The web experience ships in English and Vietnamese with the design
system, keyboard navigation, and reduced-motion support. Cloudflare work is
bounded per request or event, and asynchronous rewards or notifications require
idempotent processing and a durable stop path.

The publication hold lifts after the canonical `/lms` mount passes signed-in
acceptance. Each shared education migration requires review before publication.

## Education center integrations

Current education-center operations use Contacts groups for rosters, class
sessions, attendance, and daily and periodic reports. Finance bills tuition for
a contact and their class using those same groups, schedules, and attendance
records. LMS preserves the saved identifiers, configuration, history, and API
contracts behind these workflows. Existing workspaces can adopt LMS without an
import, backfill, or data migration.

| Workflow | Existing source | LMS behavior |
| - | - | - |
| Learners, teachers, and assistants | Contacts workspace users, explicit platform-account links, and group membership | Use the same contact and group IDs. Each LMS class or independently rostered section uses its Contacts group. The existing manager-only membership operation owns enrollment and role changes. Scope invitations and join codes to that operation and keep the original membership date and audit history. |
| Guardians and contact profiles | Contacts contact details and explicit Learn invitation and consent links | Resolve notification recipients from authorized Contacts data. Verified, active guardian links authorize access to the intended learner. Signed-in Contacts profiles can link to LMS progress and released grades. Public profile shares carry no new academic fields or access grants. |
| Timetables and attendance | Contacts group session recurrence, scheduled occurrences, canceled exceptions, and group attendance | Read the same occurrence IDs, time zone, and roster. Calendar displays those sessions. Teach records marks through the group attendance workflow, so the same edits appear in Contacts and feed the existing Finance policy. |
| Reports | Contacts daily post checks and periodic reports, including approvals, stages, and delivery history | Show the same reports in Contacts and share only eligible results in Learn. Keep skipped historical delivery records, recipient verification, review and send controls intact. |
| Tuition and payments | Finance invoice customer, invoice-to-group links, payment transactions, and tuition coverage | Show the billing period and payment status in the class roster only with the existing Finance permission. Link to Finance with the selected contact and group. Finance owns invoicing, settlements, cancellations, credits, and audits. |
| Discounts | Finance promotions, saved invoice discounts, and linked promotion eligibility | Use Finance's existing promotion selection and validation when billing tuition. Preserve the terms recorded on historical invoices. |

Use `workspace_users`, `workspace_user_linked_users`, `workspace_user_groups`,
and `workspace_user_groups_users` as the identity and roster join. Calendar
views use Contacts' resolved group sessions and `user_group_attendance`
records. Finance links `finance_invoices.customer_id` to the same workspace
user and `finance_invoice_user_groups` to the same class. An invoice can cover
more than one class. Finance's explicit `subscription_months` and legacy
coverage remain authoritative, including the membership start date, planned
and canceled sessions, configured attendance billing, and linked tuition
products. LMS displays Finance's status without recalculating or duplicating it.
See [Contacts](https://docs.tuturuuu.com/platform/applications/contacts.md),
[Finance tuition coverage](https://docs.tuturuuu.com/platform/applications/finance.md#subscription-coverage-and-tuition-reporting),
and [Reports](https://docs.tuturuuu.com/platform/applications/reports.md).

Meet owns live sessions and participant intervals. Link live sessions to a
lesson and its class occurrence. When Meet attendance is enabled, match only
verified identities to the class roster and feed the existing Contacts
attendance workflow. Preserve staff corrections and keep guest identities
unmatched until staff can verify them. Drive owns file permissions and links
for lesson resources and submissions. Mail and notifications deliver class
announcements and assignment reminders through their existing recipient and
delivery controls. Tasks can show teacher follow-ups and grading work linked
to the LMS item. The LMS submission and gradebook remain authoritative for
the outcome.

Every cross-app action checks the destination app's workspace and resource
permissions, even when a link starts in another app. Add new fields or views
without changing existing response shapes, routes, or writes. Verify that the
same group and student appear in Contacts and LMS, the same class occurrence
appears in the schedule and attendance views, and Finance gives the same
tuition result before and after LMS adoption. Check that a roster viewer
without invoice access sees no billing information. Keep those comparisons
read-only for active workspaces and exercise writes in a controlled workspace.
The existing Contacts attendance, report scope, and Finance
pending-tuition and subscription-context regressions anchor these checks.

## Mobile JSON API

Use the platform `/api/v1/workspaces/{wsId}/education` prefix. Mobile and web
must preserve the same membership, resource, and release rules. Treat
authorization and the selected learner as part of local cache identity.
Mobile can send its signed-in Supabase access token as `Authorization: Bearer`.
Return stable error codes alongside messages. Paginate collections and bound
each request. Delta feeds require a server-owned `updated_at` and a way to
reconcile deleted rows and permission changes. Preserve older API paths and
response fields while clients adopt the new contracts.

### Class catalog

`GET /api/v1/workspaces/{wsId}/education/classes` is a read-only catalog.
It shares the learner API availability gate and returns 404 while that gate is
held. Use the platform session or a verified app session scoped to the
requested view.

| Query | Behavior |
| - | - |
| `view=learning` | Default. A learner sees published classes where their Contacts record has a student membership. An approved linked guardian sees the selected learner's same catalog. Use `student_id` for explicit guardian selection. Learn app sessions are accepted. |
| `view=staff` | A workspace member with group view permission can request the staff catalog. Group managers see active non-guest class groups, including drafts. Other staff see only groups where their Contacts record is a teacher. Teach app sessions are accepted. |
| `after` | Opaque continuation value from the last response. Keep the same workspace, view, and selected learner when replaying it. |
| `limit` | Optional integer from 1 to 50. Defaults to 20. |

The response includes `role` (`student`, `guardian`, `teacher`, or
`administrator`), `read_only`, `data`, and `next_cursor`. The role identifies
the projection and grants no mutation permissions. `read_only` is true for
guardians and the staff catalog. Rows have `id`, `name`, `description`,
`is_course_published`, and `updated_at`. The ID is the existing Contacts group
ID. The current group schema has no reliable modification timestamp, so
`updated_at` is null. Read the catalog from the start to reconcile membership,
unpublishing, and removals. A non-null `next_cursor` continues the UUID-ordered
catalog. The API provides neither a total count nor a grade projection.

Errors use `{ code, message }`. Handle `LMS_INVALID_QUERY` (400),
`LMS_UNAUTHENTICATED` (401), `LMS_FORBIDDEN` (403),
`LMS_NOT_AVAILABLE` (404), and `LMS_UNAVAILABLE` (500).
All responses are private and uncached. Existing application APIs keep their
original contracts.

### Staff class roster

`GET /api/v1/workspaces/{wsId}/education/classes/{classId}/roster` uses the
same availability gate as the catalog. Pass a platform or Teach app session,
the class's Contacts group ID, and optional `after` and `limit` (1–50, default
20\). The caller needs group view permission and Contacts name access
(`view_users_public_info` or `view_users_private_info`). A caller with group
update permission can read the workspace's active class groups. Other staff
can read a class only while their active workspace contact is assigned as
its teacher. Student and guardian screens use the learning catalog.

The response includes `class_id`, the staff projection `role`, `data`, and
`next_cursor`. Each row contains `contact_id`, `name`, the recorded membership
`role`, `joined_at`, and `updated_at`. Contact ID is the cursor order. Archived
contacts and rows from another workspace are excluded. The response contains
no contact emails, guardian details, billing, or grades. Membership rows have
no reliable modification timestamp, so `updated_at` is null and clients
reconcile membership removals by restarting from the first page. A missing or
inaccessible class returns `LMS_CLASS_NOT_FOUND` (404). Other errors follow the
class catalog contract.

### Class lesson outline

`GET /api/v1/workspaces/{wsId}/education/classes/{classId}/lessons` returns
the class lesson list using the same availability gate and view permissions as
the class catalog. `view=learning` is the default. Students and authorized
guardians see published lesson outline rows for a published, enrolled class.
`view=staff` includes drafts for an assigned teacher or group manager. The
class ID is the existing Contacts group ID. Pass `student_id` to select an
authorized guardian subject, `limit` for a page of 1–50 rows (default 20), and
`after` to replay the previous `next_cursor` unchanged.

The response contains `class_id`, `role`, `read_only`, `data`, and
`next_cursor`. Each row contains `id`, `name`, `sort_key`, `is_published`, and
`updated_at`. The lesson ID is the existing course module ID. Rows are ordered
by `sort_key`, then ID. No reliable lesson modification timestamp is available,
so `updated_at` is null. Read from the first page after reorder, access, or
publication changes. Titles can include lessons that require prerequisites.
Opening a lesson, downloading files, and taking assessments each require
their respective resource permissions. The outline returns only metadata.

Responses are private and uncached. An inaccessible class returns
`LMS_CLASS_NOT_FOUND` (404). An accessible class with no visible or remaining
lessons returns an empty `data` array. Other errors follow the catalog contract.

### Class attendance

`GET /api/v1/workspaces/{wsId}/education/classes/{classId}/attendance`
reads the existing Contacts attendance records under the LMS availability gate.
Pass `from` (inclusive) and `to` (exclusive) as calendar dates in
`YYYY-MM-DD` format, with a maximum window of 90 days. Use `after` and
`limit` (1–50, default 20) to page. A continuation uses the same date window,
workspace, class, view, and selected learner.

`view=learning` is the default. A student or authorized guardian sees only
the selected learner's marks in a published class with an active enrollment.
`view=staff` shows class marks to assigned teachers and group managers with
group view permission. Pass `student_id` for an authorized guardian selection.

The response contains `class_id`, `role`, `data`, and `next_cursor`.
Rows contain `id`, `contact_id`, `date`, `session_id`, `status`, and
`updated_at`, ordered by date then ID. A null `session_id` identifies an
existing date-based mark. The status is the value recorded in Contacts.
Staff notes stay in Contacts. Attendance rows currently have no authoritative
modification timestamp, so `updated_at` is null. Refresh from the first page
after marks or access change. Responses use the class outline's private cache
policy and error codes. Existing Contacts attendance APIs retain their contracts.

### Class schedule

`GET /api/v1/workspaces/{wsId}/education/classes/{classId}/schedule` reads
the same session occurrences as the Contacts timetable under the LMS availability
gate. Use `view=learning` for a student or linked guardian, `student_id` for an
authorized guardian selection, or `view=staff` for the assigned teacher or group
manager. Request `from` (inclusive) and `to` (exclusive) as ISO 8601 timestamps
with a timezone. They filter the session start time. Each window covers up to
90 days. Set `limit` from 1 to 50 (default 20) and replay `next_cursor` as
`after` using the same selection and window.

The response contains `class_id`, `role`, `data`, and `next_cursor`.
Each row has the existing session `id`, `title`, `starts_at`, `ends_at`,
`start_timezone`, `end_timezone`, `status` (`scheduled` or `cancelled`),
and the database's `updated_at`. Rows sort by start time then ID. Schedule
records can refer to the same `session_id` used by attendance. Use
`updated_since` for inclusive filtering by modification time and merge by
session ID. Preserve timestamp precision and refresh the full window to
reconcile removals, moves outside the window, and access changes. Session
descriptions, files, and meeting links have their own resource permissions.
Responses use the class outline's access errors and private cache policy.

### Class tuition invoices

`GET /api/v1/workspaces/{wsId}/education/classes/{classId}/tuition-invoices`
returns Finance invoice links for current learners in the class roster. Use
a platform or Teach app session. The caller must be an assigned teacher or
group manager with group view permission and Finance's `view_invoices`
permission. Use `contact_id` to filter by the roster's Contacts ID. Page with
`limit` from 1 to 50 (default 20) and the previous `next_cursor` as `after`.

The response contains `class_id`, `role`, `data`, and `next_cursor`.
Rows are ordered by `invoice_id` and include `contact_id`, Finance's recorded
`completed_at`, `subscription_months`, and `valid_until`. `status` is
`completed` when Finance has a completion timestamp and `open` otherwise.
Use `invoice_id` to open the authorized Finance invoice. Finance still
determines the periods covered, outstanding tuition, promotions, and payment
amounts. An empty page means there are no visible invoice links in the current
selection. This read uses existing invoice and class links. `updated_at` is
null because invoices have no authoritative modification timestamp.
Responses use the attendance endpoint's privacy and stable error rules.

Mobile integration still requires separate versioned contracts for class
mutations, lesson materials and completion, assessment delivery and grades,
assignment submissions, notifications, and rewards. Learner and teacher screens
use only their own projections. Forward links can continue opening the authorized
Contacts, Finance, Calendar, Meet, Drive, Mail, and Tasks surfaces as their
specific JSON contracts land.

## Routes and canonical URLs

| Canonical path | Purpose |
| - | - |
| `/lms` | Public entry |
| `/lms/login` | Shared sign-in entry through Web |
| `/lms/teach/{workspace}/…` | Teaching workspace and existing teaching deep links |
| `/lms/learn/{workspace}/…` | Learning workspace and existing learning deep links |
| `/lms/learn/parent-invite` | Parent invitation handoff |

The area segment precedes the existing route path. This preserves localized
links, workspace aliases, course IDs, modules, lesson IDs, and invitation
parameters without overloading a shared URL with two access models. Legacy locale
segments stay in the initial redirect. The receiving area stores the selected
locale before continuing to the unprefixed path.

| Incoming URL | Permanent destination after cutover |
| - | - |
| `https://teach.tuturuuu.com/{path}`, `https://tuturuuu.com/teach/{path}` | `https://tuturuuu.com/lms/teach/{path}` |
| `https://learn.tuturuuu.com/{path}`, `https://tuturuuu.com/learn/{path}` | `https://tuturuuu.com/lms/learn/{path}` |
| `https://lms.tuturuuu.com/{path}` | `https://tuturuuu.com/lms/{path}` |

Navigation redirects use HTTP 301 and preserve encoded paths and the query
string, including repeated parameters. Exercise non-GET API clients against
their existing origins before retiring compatibility routes. Public LMS
documents declare their apex canonical URL. Private pages, authentication
pages, and staging hosts carry `noindex`.

## Session and performance

The apex mount uses the shared Tuturuuu session. Teach loaders share one bootstrap result per rendered request. The mounted
Teach and Learn menus use their verified bootstrap profile. Each mutation
continues to enforce its own resource and session checks. Fingerprinted assets may be cached immutably.
Authenticated documents, data, and authentication redirects remain private.
The initial consolidation introduces no background jobs.

## Migration and rollback

Use TanStack Start, Vite+, and Void on Cloudflare. Introduce `apps/lms` as a
separate deployment identity so the active Teach deployment and the retained
Learn deployment stay available during qualification. The entry Worker dispatches Teach and Learn paths through service bindings
to the existing runtimes, with each area serving its own assets and APIs.
Both areas use the shared education packages. Keep course, enrollment, and progress
records in place.

1. Qualify the route-free LMS artifact in Workerd and on a pinned staging
   version. Record the source SHA, artifact digest, and host, session, asset,
   and latency checks.
2. The gateway owner captures the current serving versions, bindings, routes,
   and DNS, then mounts LMS at `/lms`. Verify signed-in teacher, administrator,
   learner, dual-role, and unauthorized workspace paths. Compare cold and warm
   header latency for landing, dashboard, and asset requests.
3. Activate the permanent legacy redirects after canonical verification.
   Exercise localized lessons, quiz authoring, attendance, grading, progress,
   and invitation deep links from every old entry.
4. Restore the captured gateway version and legacy routing if the mount
   regresses. Keep the canonical route serviceable for browsers retaining
   a permanent redirect. Recovery needs no data migration.

See [LMS artifact acceptance](https://docs.tuturuuu.com/build/devops/lms-start-void.md), the
[native Start runbook](https://docs.tuturuuu.com/build/devops/native-start-migration.md) and
[gateway runbook](https://docs.tuturuuu.com/build/devops/gateway-worker.md) for artifact and routing
acceptance.

## Teaching shortcuts

In a teaching workspace, open navigation search from the sidebar or press
Ctrl+K or Command+K. The launcher searches the active workspace's destinations,
including course building, quizzes and gradebook. Routes keep the same permission
checks whether opened from search, the sidebar or a deep link.

The Teach class roster opens the same group and member profiles in Contacts.
The roster shows the existing student and teacher roles. Contacts resolves
profile and group permissions before showing records.

The builder keeps the course outline and current module editor visible together
on wide screens. The attendance page lists the next seven scheduled class dates
and opens the selected date's register. Gradebook filters use the selected quiz
set and date range. Selecting All leaves quiz sets unrestricted within the
workspace.

## Learner workspace

Home's Next up section links to an in-progress course first, then the first
unstarted course. It shows the course's module completion alongside open work.
Assessments open their own pages and other work opens the assignments list.
The linked learner selection stays attached to both kinds of links. The course outline marks completed and locked modules. Resume lesson opens the
first published, unlocked, unfinished module in course order. Library uses the
same course catalog and loads lesson materials for the selected course only.
Assignments separates open and completed work. A guardian in read-only mode
can browse both lists and review released assessment results. It does not offer
assignment completion controls in that mode.

Library lists unlocked modules and preserves the linked learner selection when
opening a module. Progress combines the report feed with a link to marks.

These views keep course and module queries scoped to the workspace and selected
learner. Learner link coverage lives in the Learn application tests.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.