Product decision
Tuturuuu LMS useshttps://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.
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
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.
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,
Finance tuition coverage,
and Reports.
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.
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.
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
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.
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. Introduceapps/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.
- 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.
- 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. - Activate the permanent legacy redirects after canonical verification. Exercise localized lessons, quiz authoring, attendance, grading, progress, and invitation deep links from every old entry.
- 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.