Skip to main content

Web Workflows

:::info Source Sourced from docs/09-frontend-workflows.md in the documentation repo. :::

Companion: 07 Epics & Stories · 10 Authoring Tool Spec · 11 Player Spec

This doc lists the canonical user journeys. Each entry: actors, trigger, steps, primary services touched, AI/offline behavior, and which steps are E2E test gates.

Critical Path Map (E2E test gates)​

* = blocking nightly E2E gate.

IDJourney
J-1*Sign up + onboarding (org tenant)
J-2*Sign in via SSO and switch tenant
J-3Reset password
J-4*Author publishes a course (manual)
J-5*Author publishes a course with AI co-author
J-6Author imports a SCORM zip
J-7*Provider lists course on marketplace
J-8*Org buys seat pack and assigns seats
J-9*Individual buys course
J-10*Org admin assigns recurring training
J-11*Learner takes course online + earns certificate
J-12*Learner takes course offline + syncs
J-13*Learner uses AI tutor (online)
J-14*Learner uses AI tutor (offline / local model)
J-15Learner gets next-step recommendation
J-16*Org admin views compliance dashboard
J-17Provider views payouts
J-18Tenant configures SSO + data residency
J-19*Multi-device: edit on web, see on mobile
J-20*Multi-device: take course on phone, resume on tablet
J-21*Compliance officer exports AI audit
J-22Public verifier verifies a certificate
J-23GDPR data export request
J-24Tenant admin defines a Dynamic Group
J-25*Author resolves an offline conflict

J-1 Sign Up + Onboarding (Org Tenant)​

Actor: Org Admin · Trigger: marketing site signup.

  1. Email + password OR magic link.
  2. Verify email.
  3. Provision org → name, slug, region.
  4. Invite first 5 colleagues.
  5. Configure plan (trial start).
  6. Land on dashboard with empty-state CTAs.

Services: identity, tenant, billing (trial), notification. AI: AI suggests org name slugs and a welcome email tone (opt-in). Offline: not relevant. E2E: gate; must complete in <90s.

J-2 Sign In via SSO + Switch Tenant​

Actor: any · Trigger: "Sign in with SSO".

  1. Pick provider (SAML/OIDC).
  2. Round-trip IdP.
  3. Land on default tenant dashboard.
  4. Open tenant switcher → pick another tenant.
  5. JWT re-minted; UI re-keyed.

Services: identity, tenant. Offline: device-bind invocation if first sign-in on device. E2E: gate (per provider type).

J-3 Password Reset​

Standard flow. Rate-limited. Link expires in 1h.

J-4 Author Publishes (Manual)​

Actor: Author.

  1. New course → modules → lessons.
  2. Add blocks: text, image, video, quiz, scenario.
  3. Live preview (LTR + RTL).
  4. Submit for review.
  5. Reviewer approves.
  6. Publish → spinner backed by saga progress UI.
  7. Confirmation: catalog link + share to marketplace prompt.

Services: authoring → content → catalog → marketplace (optional) → notification. Offline: drafts editable offline (J-25 covers conflicts). E2E: gate; full saga + state machine.

J-5 Author Publishes With AI Co-Author​

Actor: Author.

  1. New course from "Generate from PDF" → upload PDF.
  2. AI segments → suggests modules + lessons.
  3. Per-lesson, AI generates blocks (status='draft_ai').
  4. Author reviews each AI block (Accept / Edit / Reject).
  5. AI generates quiz from lesson; author edits.
  6. AI translates entire course to ar-SA + fr-FR.
  7. Author requests TTS narration for one module.
  8. Submit for review → publish.

Services: authoring, ai-gateway, media (image + TTS), assessment, content, catalog, notification. AI: every artifact carries provenance; refusals handled gracefully. Offline: PDF upload requires online; AI requests fall back to local model offline (degraded). E2E: gate.

J-6 Import SCORM​

Actor: Provider Admin / Author.

  1. Upload SCORM 1.2 zip in author UI.
  2. Validation runs (manifest + asset check).
  3. Normalized into a CourseDraft preview.
  4. Author can edit or publish as-is.

Services: content, authoring, media.

J-7 Provider Lists Course on Marketplace​

Actor: Provider Admin.

  1. Pick a published course.
  2. Define pricing plans (one-time, sub, seat pack, site).
  3. Marketing copy + screenshots.
  4. AI moderation → Submit for approval.
  5. Platform-admin approves → listing live.

Services: marketplace, ai-gateway (moderation), media, catalog, notification.

J-8 Org Buys Seat Pack + Assigns​

Actor: Org Admin.

  1. Browse marketplace.
  2. Add seat pack to cart → pay (Stripe/Adyen/Tap).
  3. License granted → org sees "X seats available".
  4. Assign seats to org units / users (or open self-claim link).
  5. Each assigned user: enrollment created → notification.

Services: marketplace, billing, enrollment, tenant, notification. E2E: gate; saga end-to-end.

J-9 Individual Buys Course​

Actor: Individual Learner. Same as J-8 but for an individual tenant; auto-enrollment to themself.

J-10 Org Admin Assigns Recurring Training​

Actor: Org Admin.

  1. Pick course → "Assign".
  2. Select target (org unit / dynamic group).
  3. AI suggests RRULE (e.g., yearly cybersecurity); admin tweaks.
  4. Set due offset + grace + escalation.
  5. Activate → ComplianceWindows materialized.
  6. Reminders fire per policy.

Services: assignment, tenant, ai-gateway, enrollment, notification. E2E: gate.

J-11 Learner Takes Course Online + Earns Certificate​

Actor: Employee Learner.

  1. Land on dashboard → see assigned course.
  2. Open course → Player launches.
  3. Navigate lessons; play media; answer quizzes.
  4. Optionally call AI tutor (J-13).
  5. Complete final quiz → completion recorded.
  6. Certificate appears in profile + email.

Services: delivery, assessment, progress, certification, notification. E2E: gate.

J-12 Learner Offline End-to-End​

Actor: Employee Learner (mobile).

  1. While online, "Download for offline" on a course.
  2. Bundle downloads (signed + encrypted; license envelope issued).
  3. Plane mode: open Player → play full course offline.
  4. Quizzes scored locally; statements queued; certificate provisional.
  5. Land. Reconnect. Sync flushes statements + claim → certificate confirmed.

Services: content, sync, delivery, progress, certification, ai-gateway (local). E2E: gate; airplane-mode flow + multi-device.

J-13 AI Tutor Online​

  1. Inside player, open Assistant panel.
  2. Ask question.
  3. SSE-streamed answer; tool calls render inline (e.g., lookupBlock).
  4. Rate response.

Services: delivery, ai-gateway.

J-14 AI Tutor Offline​

Same UX, local model used; provenance "Local model"; cloud-refresh CTA when online.

J-15 Next-Step Recommendation​

Post-completion, recommendation drawer suggests next courses with reasoning.

J-16 Org Compliance Dashboard​

Actor: Org Admin / Manager.

  • Dashboard widgets: completion rate by org unit, overdue users, time-to-complete distribution, AI insight narrative. Services: analytics, assignment, ai-gateway. E2E: gate (with seeded fixtures).

J-17 Provider Payouts​

Provider sees current period, earnings by listing, payout schedule.

J-18 SSO + Data Residency​

Tenant admin configures SAML/OIDC, sets data residency (us / eu / me / ap). Migration saga visible.

J-19 Multi-device Edit Visibility​

Author edits a draft on web; mobile shows live updates within seconds (Yjs awareness + sync deltas).

J-20 Resume Across Devices​

Learner starts on phone, resumes on tablet within 60s; cursor reconciled to max position.

J-21 Compliance Officer AI Audit Export​

  1. Open Compliance → "AI Audit".
  2. Filter by date range, prompt, model, decision id.
  3. Export CSV/JSONL → notification with download link. Services: ai-gateway, analytics, notification. E2E: gate.

J-22 Public Cert Verification​

Open /verify/{token} → display issuance details + status; no auth.

J-23 GDPR Export​

User clicks "Download my data" in profile → request raised → all services contribute → zip emailed.

J-24 Dynamic Group​

Org admin builds query (e.g., dept = engineering AND country in [DE, FR]) → preview matched users → save.

J-25 Offline Authoring Conflict​

Actor: two Authors editing the same lesson.

  1. Both go offline.
  2. Both edit the same block.
  3. Reconnect → server detects conflict for that block (LWW + diff because Yjs CRDT not engaged due to offline edits).
  4. Conflict UI shows side-by-side; user picks.
  5. Outbox flushes; mutation applied.

Services: sync, authoring. E2E: gate.

Cross-Journey Conventions​

  • Every journey logs analytics events used by 12 Analytics dashboards.
  • Every journey honors LTR + RTL.
  • Every journey has a measured perf budget (LCP, INP).
  • Every AI step displays provenance + budget consumption.
  • Every offline step shows sync status + recoverability.

Why This Set​

These journeys cover all six product surfaces (provider, org admin, manager, employee learner, individual learner, compliance) plus the offline + AI cross-cutting capabilities. Gating nightly E2E on the starred ones catches regressions in multi-service sagas (publish, purchase, assignment, sync) — which is where bugs in event-driven systems hide.