classroomio/FEATURE_AUDIT.md

ClassroomIO — Feature & Flow Map (QA Audit)

Purpose of this document: a reverse‑engineered, citation‑backed map of every feature in the ClassroomIO application, produced for QA to build test cases and record demo videos. Files are the source of truth. Every claim is backed by a file reference. Claims that could not be traced to code are marked ⚠️ UNVERIFIED. Ambiguities live in §7 Open Questions, not in the body.

Reference format: `path/to/file` → symbol/lines — what it proves. Scope (per QA request): full depth on the user‑facing product (apps/dashboard, apps/api, apps/website, apps/embeds + the packages that back features); a lighter Supporting Infrastructure summary for the rest. PRD folders (prd/*) are used only to cross‑check intent — code wins on conflict.

---

1. System Overview

What it is. ClassroomIO is an open‑source Learning Management System (LMS) for companies — compliance/employee training, customer education, and partner certification. It supports multi‑organization workspaces, courses/lessons/exercises, cohorts (cohorts), certificates, an AI course builder + in‑lesson tutor, a public REST API, an MCP server, and embeddable course widgets. It can be self‑hosted or run as the cloud product. (README.md → lines 11–50 — feature summary; README.md → 84–91 — monorepo apps.)

Tech stack (cited from manifests):

• Monorepo: pnpm + Turbo. package.json → root scripts/workspaces; pnpm-workspace.yaml → packages globs (apps/*, packages/*, packages/course-app/src/*); turbo.json.
• Frontend: SvelteKit + Svelte 5 + TailwindCSS. README.md → 52–58 ("Built With"); apps/dashboard/svelte.config.js.
• Backend API: Hono (TypeScript). apps/api/src/app.ts → new Hono() app; ARCHITECHTURE.md → layered architecture (Routes → Services → Queries).
• Database: PostgreSQL via Drizzle ORM. packages/db/src/schema.ts (~3,400 lines of pgTable/pgEnum); packages/db/src/drizzle.ts.
• Auth: Better Auth (sessions, OAuth, SSO). apps/api/src/app.ts → 12, 107–188 (auth.handler, /api/auth/*); packages/db/src/auth.ts.
• Background jobs: BullMQ + Redis. apps/jobs, apps/api/src/routes/admin/queues.ts (mountQueueDashboard), mediaJob/jobStep/deadLetterJob tables in schema.ts.
• Object storage: S3‑compatible / MinIO. .env.example → 77–89 (OBJECT_STORAGE_*); README.md → 176–191.
• Billing: Polar. apps/dashboard/src/routes/api/polar/*.
• AI providers: OpenAI / Google (Gemini) / Anthropic. .env.example → 110–115; packages/utils/src/agent-models (per README.md → 236).

High‑level architecture (ARCHITECHTURE.md → 9–51):

SvelteKit dashboard (apps/dashboard)  ──RPC (Hono client)──▶  Hono API (apps/api)
        │  server-side SSR proxy (.server.ts, PRIVATE_SERVER_KEY)        │
        │                                                                 ▼
   Public org sites / embeds                              Services → Queries (Drizzle)
   (apps/website, apps/embeds)                                     │
                                                                   ▼
                                              PostgreSQL · Redis/BullMQ · S3/MinIO

• Layered API: Routes (HTTP/validation/auth) → Services (business logic/ transactions) → Queries (pure Drizzle). ARCHITECHTURE.md → 44–50.
• Shared Zod validation in packages/utils/src/validation/*, used by both API and dashboard. ARCHITECHTURE.md → 45; AGENTS.md → 17–25.
• Dashboard talks to the API through a typed Hono RPC client and an SSR auth proxy authenticated with PRIVATE_SERVER_KEY. README.md → 149–156.

---

2. Feature Inventory

Status legend: Complete = route+service+schema present; Partial = present but gated/limited or doc claims exceed code; Stub/Planned = PRD only, little/no code.

#	Feature	Purpose	Primary files	Status
1	Authentication & sessions	Email/password, OAuth, session mgmt	apps/api/src/app.ts:107, packages/db/src/auth.ts	Complete
2	Signup gating	Org‑scoped/invite‑only/self‑host bootstrap rules	apps/api/src/middlewares/signup-guard.ts	Complete
3	Onboarding & org creation	Create profile + first organization	apps/api/src/services/onboarding.ts, apps/dashboard/src/routes/(auth)/onboarding	Complete
4	Organizations (workspaces)	Multi‑org, settings, members, plan	apps/api/src/routes/organization/organization.ts, schema.ts:1949	Complete
5	Team / people management	Invite teachers, assign roles	apps/api/src/routes/course/people.ts, apps/dashboard/src/lib/features/people	Complete
6	Courses	Create/manage courses, sections, content	apps/api/src/routes/course/course.ts, schema.ts:634	Complete
7	Lessons & lesson editor	Lesson content, multilingual, comments	apps/api/src/routes/course/lesson.ts, .../lesson-language.ts, schema.ts:956	Complete
8	Exercises & questions	Quizzes, question types, sections, grading	apps/api/src/routes/course/exercise.ts, .../submission.ts, .../mark.ts, packages/question-types	Complete
9	Course people / enrollment	Enroll students, roster	apps/api/src/routes/course/people.ts	Complete
10	Course invites	Email + link invites with audit	apps/api/src/routes/course/invite.ts, apps/api/src/services/course/invite.ts, schema.ts:1282	Complete
11	Org invites	Invite org members (EMAIL/LINK)	apps/api/src/routes/invite/invite.ts, schema.ts:1384	Complete
12	Compliance training	Deadlines, renewals, grace, records	apps/api/src/routes/course/compliance.ts, apps/api/src/routes/internal, schema.ts:768 (courseCompletionRecord)	Complete
13	Certificates	Issue branded certificates	packages/certificates/src/render.ts, schema.ts:850 (courseCertificateIssue)	Complete
14	Cohorts	Group courses, goals, members, newsfeed	apps/api/src/routes/cohort/cohort.ts, schema.ts cohort tables	Complete
15	Community Q&A	Per‑course questions/answers	apps/api/src/routes/community/community.ts, schema.ts:1558	Complete
16	Course newsfeed	Course/cohort announcements + comments	apps/api/src/routes/course/newsfeed.ts, schema.ts:1605	Complete
17	Attendance	Track group/live‑class attendance	apps/api/src/routes/course/attendance.ts, schema.ts:321 (groupAttendance)	Complete
18	AI Course Assistant	In‑course AI authoring/plan/edit chat	apps/api/src/routes/agent/*, packages/ai-assistant, schema.ts:3163 (aiAgentRun)	Complete (key‑gated)
19	AI Lesson Tutor	In‑lesson learner AI helper + fair‑use caps	apps/api/src/routes/course/ai-tutor.ts, apps/api/src/routes/organization/ai-tutor.ts, schema.ts:3013 (aiTutorMessageCount)	Complete (key‑gated)
20	AI credits / token billing	Token usage, balance, purchases	schema.ts:2919 (aiTokenUsage), apps/dashboard/src/lib/features/agent/api/credit-purchase.server.ts	Complete (cloud billing)
21	Course import	Import from prompt/PDF/course	apps/api/src/routes/organization/course-import.ts, apps/api/src/services/course-import, schema.ts:2603	Complete
22	Media manager	Upload/manage video/docs/media, transcripts	apps/api/src/routes/media/media.ts, .../transcripts.ts, .../hls.ts, apps/dashboard/src/lib/features/media, schema.ts:1028 (asset)	Complete
23	Tags	Tag groups/tags/assignments for courses	apps/api/src/routes/organization/tags.ts, schema.ts:2158	Complete
24	Org public site (org‑site)	Branded public course catalog/pages	apps/api/src/routes/org-site, apps/dashboard/src/routes/(org-site)	Complete
25	Custom domains	Cloudflare custom domain mapping	apps/api/src/routes/domain/domain.ts, apps/tenant-router	Complete
26	Course widget embed	Embeddable course catalog widget	apps/api/src/routes/widgets, apps/dashboard/src/routes/(app)/widgets, apps/embeds, schema.ts:2255 (widget)	Complete
27	Public REST API (v1)	API‑key automation: courses, audience	apps/api/src/routes/v1/*, apps/api/src/services/v1, schema.ts:2539 (organizationApiKey)	Complete
28	Automation / API keys	Issue mcp/api/zapier keys with scopes	apps/api/src/routes/organization/automation.ts, apps/api/src/middlewares/automation-key*.ts	Complete
29	MCP server	@classroomio/mcp AI‑native course authoring	packages/mcp/src/*	Complete
30	Enterprise SSO	OIDC SSO (Okta/Google Workspace/Auth0)	apps/api/src/routes/organization/sso.ts, apps/api/src/routes/sso/discovery.ts, schema.ts:2479 (organizationSsoConfig)	Complete (licensed)
31	Token auth	Token‑based auth policy	apps/api/src/routes/organization/token-auth.ts, schema.ts:2513 (organizationTokenAuth)	Complete (licensed)
32	Licensing	Self‑host license‑gated features	apps/api/src/routes/license.ts, apps/api/src/middlewares/license.ts, packages/utils/src/license/*	Complete
33	Billing (Polar)	Subscriptions + AI token packs	apps/dashboard/src/routes/api/polar/*	Complete (cloud only)
34	Analytics	Login/page events, org/course/country daily	apps/api/src/routes/dash, apps/api/src/services/analytics, schema.ts:167–285	Complete
35	Email / notifications	Transactional emails via jobs	apps/api/src/routes/mail, packages/email, apps/api/src/services/jobs	Complete
36	Background jobs	Media/email queues, BullMQ dashboard	apps/jobs, apps/api/src/routes/jobs, apps/api/src/routes/admin/queues.ts	Complete
37	Unsplash image search	Image picker for content	apps/api/src/routes/unsplash/unsplash.ts	Complete
38	Marketing website	classroomio.com landing	apps/website	Complete
39	Documentation site	classroomio.com/docs	apps/docs	Complete
40	Outbound webhooks	Emit certificate.issued, etc.	prd/webhooks (todo)	Stub/Planned ⚠️
41	SCORM support	SCORM package support	prd/scorm-support (todo)	Stub/Planned ⚠️
42	Notification system	In‑app notifications	prd/notification-system (todo)	Stub/Planned ⚠️

Items 40–42 are listed in PRD-TRACKER.md → 9, 16, 24 as todo; treat as not yet shipped. See §7.

---

3. Per‑Feature Detail

3.1 Authentication & Sessions

• Purpose: authenticate users (email/password + OAuth) and attach org roles to the session.
• How it works: All /api/auth/* requests are handled by Better Auth via auth.handler. apps/api/src/app.ts → 107–188. A global middleware resolves the session on every request and sets user, session, and orgRoles into context. apps/api/src/app.ts → 60–97. The app rebuilds the request host from X-Forwarded-Host/-Proto (Cloudflare proxy) and uses a Redis "oauth handoff" to shrink large OAuth callback cookies into a short token. apps/api/src/app.ts → 110–173.
• User flow: Login page → submit email/password (or OAuth) → Better Auth sets session cookie → dashboard reads /session. apps/dashboard/src/routes/(auth)/login; apps/api/src/app.ts → 189–199 (/session).
• Key files: apps/api/src/app.ts, packages/db/src/auth.ts, packages/db/src/auth/hooks/create-profile.ts.
• Edge cases: OAuth cookie > 500 chars routed through Redis token (app.ts:160); getSession failures fall through as anonymous (app.ts:71–84); session carries orgRoles map used by RBAC middlewares (app.ts:88).

3.2 Signup Gating (signupGuard)

• Purpose: enforce org‑level and deployment‑level signup rules server‑side.
• How it works: apps/api/src/middlewares/signup-guard.ts → 129–159. With a cio-org-id header: rejects when org.disableSignup (403 SIGNUP_DISABLED, line 148) or when settings.signup.inviteOnly and the email lacks an active invite (403 INVITE_REQUIRED, lines 97–113). Without the header: cloud passes through; self‑hosted requires org context unless no org exists yet (bootstrap) or the email already belongs to the org. Lines 75–91 (canProceedWithoutOrgContext).
• User flow: Signup form → POST /api/auth/sign-up/* (guarded, app.ts:106) → allowed / SIGNUP_DISABLED / INVITE_REQUIRED / ORG_CONTEXT_REQUIRED.
• Edge cases (tester probes): invite‑only org without invite; disabled signup; self‑hosted with no cio-org-id and an existing org; unparseable body → 400 INVALID_REQUEST.

3.3 Onboarding & Organization Creation

• Purpose: create the user profile and first organization, then send a welcome email.
• How it works: apps/api/src/services/onboarding.ts. createOrganizationWithOwner validates site‑name uniqueness (409 SITENAME_EXISTS, lines 36–40), creates org + admin member in a transaction (lines 44–61), and on self‑hosted assigns the org an ENTERPRISE plan with provider selfhosted (lines 64–77). Self‑hosted blocks a second org (403, lines 28–33). completeOnboarding enqueues a welcome email (lines 121–134).
• User flow: Signup → (auth)/onboarding → enter name/org/site name → org+admin created → dashboard.
• Edge cases: duplicate site name (409 + Postgres 23505 fallback, lines 93–95); second‑org attempt on self‑host; profile not found (404).

3.4 Organizations (Workspaces)

• Purpose: the top‑level tenant; owns courses, members, settings, plan, branding.
• How it works: apps/api/src/routes/organization/organization.ts (CRUD + settings); organization table schema.ts:1949 (siteName, settings, branding, disableSignup). Members live in organizationmember (schema.ts:1754) with roleId FK to role.
• User flow: Org switcher → settings → update name/site/branding/signup policy. apps/dashboard/src/lib/features/ui/sidebar/org-sidebar/org-switcher.svelte; apps/dashboard/src/lib/features/settings.
• Edge cases: unique siteName; self‑hosted = single org (see §5); org settings drive signup gating (§3.2).

3.5 Courses, Sections & Content

• Purpose: author and deliver courses (self‑paced, live‑class, compliance, public).
• How it works: course sub‑routers under apps/api/src/routes/course/ — course.ts, section.ts, content.ts, lesson.ts, exercise.ts, people.ts, newsfeed.ts, attendance.ts, compliance.ts, mark.ts, submission.ts, invite.ts, lesson-language.ts, payment-request.ts, presign.ts, ai-tutor.ts, katex.ts (index.ts composes them). Course type enum SELF_PACED|LIVE_CLASS|COMPLIANCE|PUBLIC (schema.ts:26). Course row schema.ts:634.
• User flow: Courses → New course → add sections/lessons → add exercises → publish → students enroll. apps/dashboard/src/routes/(app)/courses/[id].
• Edge cases: course type drives compliance/public behavior; locale enum (schema.ts:27, 10 languages) drives multilingual lessons.

3.6 Lessons & Multilingual Editor

• Purpose: lesson content with notes/slides/video, comments, translations.
• How it works: lesson (schema.ts:956), lessonComment (schema.ts:516), lessonCompletion (schema.ts:1490), lessonLanguage + …History (schema.ts:1706, 1732). Routes: apps/api/src/routes/course/lesson.ts, .../lesson-language.ts. PRDs prd/lesson-edit [DONE], prd/lessons-list [DONE] confirm intent.
• User flow: Open lesson → edit content → add translation → student marks complete.
• Edge cases: language history retained; completion tracked per student.

3.7 Exercises, Question Types & Grading

• Purpose: quizzes/assessments with multiple question types and grading.
• How it works: exercise (schema.ts:1175), exerciseSection (schema.ts:1217), question/questionType/questionAnswer (schema.ts:1803–1913), submission/ submissionstatus (schema.ts:571,617), exerciseTemplate (schema.ts:2401). Routes exercise.ts, submission.ts, mark.ts. Shared types in packages/question-types. PRDs: exercise-question-types, exercise-sections [DONE], video-recording-question-type [DONE].
• User flow: Author exercise → add questions (incl. video‑recording type) → student submits → tutor/admin marks → status recorded.
• Edge cases: section‑based exercises; video‑recording answers (media pipeline); prd/selective-exercise-assignment is todo (assign specific exercises to specific students) — verify it is not yet available.

3.8 Enrollment, Course Invites & Secure Invites

• Purpose: add students to courses by email or shareable link, with audit trail.
• How it works: apps/api/src/services/course/invite.ts; courseInvite (schema.ts:1282) + courseInviteAudit (schema.ts:1342); event‑type enum schema.ts:53. Org invites: organizationInvite (schema.ts:1384, EMAIL/LINK enum schema.ts:71) + …Audit (schema.ts:1448), routes apps/api/src/routes/invite/invite.ts. PRD secure-student-invites [DONE].
• User flow: Course → People → Invite (email or link) → invitee accepts via apps/dashboard/src/routes/invite/[hash] or /invite/link/[hash] → enrolled.
• Edge cases: invite expiry/custom expiry (AGENTS.md:231 references customExpiresAt); link vs email; audit events recorded; invite‑only signup interplay (§3.2).

3.9 Compliance Training

• Purpose: deadline tracking, renewals/retake intervals, grace periods, completion records.
• How it works: apps/api/src/routes/course/compliance.ts and internal compliance router apps/api/src/routes/internal (AGENTS.md:87–98); courseCompletionRecord (schema.ts:768), courseCompletionNotificationEvent (schema.ts:824), courseCertificateIssue (schema.ts:850). Course type COMPLIANCE (schema.ts:26). PRD compliance-training-platform [DONE].
• User flow: Mark course as compliance → set deadlines/renewal → learners complete → completion record + certificate; renewal/grace events tracked.
• Edge cases: grace periods, renewal intervals, waivers (per README 21), notification events.

3.10 Certificates

• Purpose: issue branded completion certificates with custom IDs.
• How it works: packages/certificates/src/render.ts + templates/ render the certificate; courseCertificateIssue (schema.ts:850) records issuance.
• User flow: Learner completes course → certificate issued → downloadable/branded.
• Edge cases: custom certificate IDs (README 21); template selection.

3.11 Cohorts & Goals

• Purpose: group courses into cohorts with goals, members, and progress tracking.
• How it works: apps/api/src/routes/cohort/cohort.ts; tables cohort (schema.ts:2646), programCourse (2677), programMember (2704), programNewsfeed +Comment (2739,2767), programGoal/…Assignment (2829,2878) with goal‑type/ deadline/status enums (2803–2828), status enum ACTIVE|INACTIVE|ARCHIVED (2644). Middlewares cohort-member.ts, cohort-team-member.ts. PRD cohorts [DONE].
• User flow: Create cohort → add courses + members → set goals/deadlines → track progress → cohort newsfeed. apps/dashboard/src/routes/(app)/cohorts/[id].
• Edge cases: goal deadline kinds; assignment status; archived cohorts.

3.12 Community Q&A & Newsfeed

• Purpose: per‑course discussion (questions/answers) and announcements.
• How it works: apps/api/src/routes/community/community.ts with route‑specific middlewares/question-author-or-team (ARCHITECHTURE.md:241–252); tables communityQuestion/communityAnswer (schema.ts:1558,1522), courseNewsfeed/ …Comment (1605,1632). Comment‑author middlewares newsfeed-comment-author-or-team.ts, cohort-newsfeed-comment-author-or-team.ts.
• User flow: Course → Community → ask/answer; team can moderate. Newsfeed posts + comments at course and cohort level.
• Edge cases: author‑or‑team authorization (only author or course team can edit/delete).

3.13 AI Course Assistant (authoring chat)

• Purpose: in‑course AI that generates outlines, lesson content, and edits.
• How it works: apps/api/src/routes/agent/{agent,history,runs}.ts; packages/ai-assistant; run tracking in aiAgentRun/…Step/…Event (schema.ts:3163,3225,3259), conversation/model context/documents (3083,3106,3138). Disabled until a provider key is set; GET /agent/status flips to enabled:true when any of OPENAI/GOOGLE/ ANTHROPIC key is present. README.md:223–238. Selected model persisted in localStorage (classroomio-ai-chat-model), provider resolved server‑side; missing key → 503 AI_NOT_CONFIGURED (README.md:236).
• User flow: Course → AI button (only shown when enabled) → chat to build/edit course.
• Edge cases: no key → AI button hidden / 503; per‑model provider resolution; optional Tinybird observability (TINYBIRD_TOKEN).

3.14 AI Lesson Tutor + Fair‑Use Caps

• Purpose: in‑lesson AI helper for learners, with usage caps.
• How it works: apps/api/src/routes/course/ai-tutor.ts, apps/api/src/routes/organization/ai-tutor.ts; aiTutorMessageCount (schema.ts:3013)
  • aiTutorCapEvent (3050). Settings UI apps/dashboard/src/lib/features/ai-tutor-settings. PRD ai-tutor-fair-use.
• User flow: Learner in lesson → ask tutor → counts toward cap → cap event when exceeded.
• Edge cases: per‑org cap configuration; cap‑exceeded behavior.

3.15 AI Credits / Token Billing

• Purpose: meter AI token usage and sell token packs.
• How it works: aiTokenUsage (schema.ts:2919), aiCreditBalance (2950), aiCreditPurchase (2974); purchases recorded by Polar order.paid webhook → CreditPurchaseApiServer.recordPurchase. apps/dashboard/src/routes/api/polar/webhook/+server.ts → 33–82; token‑pack constants @cio/utils/plans (TOKEN_PACK.TOKENS_PER_UNIT, line 53).
• User flow: Buy tokens (/api/polar/buy-tokens) → Polar checkout → webhook credits org balance.
• Edge cases: cloud only (Polar); quantity/metadata parsing; UUID validation of triggeredBy (lines 61–66).

3.16 Course Import

• Purpose: create courses from a prompt, PDF, or existing course.
• How it works: apps/api/src/routes/organization/course-import.ts, apps/api/src/services/course-import; courseImportDraft (schema.ts:2603) with source enum prompt|pdf|course (schema.ts:29) and draft status DRAFT|PUBLISHED|ARCHIVED (30).
• User flow: Org → Import course → choose source → review draft → publish.
• Edge cases: draft lifecycle; PDF parsing pipeline (jobs/media).

3.17 Media Manager (video/docs, transcripts, HLS)

• Purpose: upload and manage media; transcode video to HLS; generate transcripts.
• How it works: routes media/media.ts, transcripts.ts, hls.ts, course/presign.ts (S3 presigned uploads). Tables asset/assetUsage (schema.ts:1028,1086), mediaJob/jobStep/mediaTranscript/deadLetterJob (schema.ts:3297,3357,3393,3447), videoTranscripts (916). Jobs processed by apps/jobs. Dashboard apps/dashboard/src/lib/features/media. PRD media-manager [DONE]. Storage via MinIO/S3 (.env.example:77–89).
• User flow: Media → upload → background transcode/transcribe → use asset in lesson.
• Edge cases: job retries / dead‑letter; HLS cross‑origin headers (app.ts:48–54); Google Drive picker optional (.env.example:99–101).

3.18 Tags

• Purpose: categorize courses via tag groups/tags.
• How it works: apps/api/src/routes/organization/tags.ts; tagGroup/tag/ tagAssignment (schema.ts:2158,2188,2225). PRD tags-feature [DONE].
• User flow: Org → Tags → create groups/tags → assign to courses → filter catalog.

3.19 Org Public Site (org‑site) & Theming

• Purpose: branded public catalog and course landing pages for an org.
• How it works: API apps/api/src/routes/org-site (mounted /org-site/course, app.ts:217); dashboard public routes apps/dashboard/src/routes/(org-site)/{course,courses}. Theme picker PRD org-landing-page-theme-picker [DONE].
• User flow: Visitor → org public site → browse courses → view course → enroll/sign up.
• Edge cases: self‑host vs cloud routing differences (see §5); org branding/theme.

3.20 Custom Domains

• Purpose: map a customer's own domain to their org site.
• How it works: apps/api/src/routes/domain/domain.ts (mounted /domain, app.ts:203); routing app apps/tenant-router. PRD custom-domain-cloudflare [DONE].
• User flow: Org settings → add custom domain → Cloudflare mapping → site served on domain.

3.21 Course Widget Embed

• Purpose: embed an org's course catalog on any external website.
• How it works: API apps/api/src/routes/widgets (mounted /widgets, app.ts:221); dashboard apps/dashboard/src/routes/(app)/widgets/[widgetId] + widget-preview; build artifacts apps/embeds (embeds:publish, README.md:256–257). Tables widget/ widgetCourse/widgetVersion (schema.ts:2255,2305,2336) with status/layout/ selection enums (42–52). PRD course-widget-embed [DONE].
• User flow: Widgets → create widget → choose courses/layout → publish → copy embed snippet (embed-preview.html).
• Edge cases: draft vs published widget; manual vs published course selection mode.

3.22 Public REST API (v1) & Automation Keys

• Purpose: programmatic access for integrations/automation.
• How it works: apps/api/src/routes/v1/{courses,audience}.ts mounted at /public-api/v1 (app.ts:218, v1/index.ts). Auth via automationKeyMiddleware + automationKeyScopesMiddleware(['public_api:*']) on every route; OpenAPI documented via hono-openapi. Courses endpoints: list/create/get/update/delete, list students, export, get/put structure (v1/courses.ts). Keys: organizationApiKey (schema.ts:2539, type mcp|api|zapier), usage tracked in organizationAutomationUsage (2574); managed via apps/api/src/routes/organization/automation.ts. PRD public-api [DONE].
• User flow: Org → API keys → create key with scopes → call /public-api/v1/... with key.
• Edge cases: scope enforcement (403 on missing scope); usage categories read|write|publish (schema.ts:32); per‑org isolation via orgId from key context.

3.23 MCP Server

• Purpose: AI‑native course authoring through the Model Context Protocol.
• How it works: packages/mcp/src/{index.ts,api-client.ts,config.ts,tools/}; published as @classroomio/mcp (README.md:258). Talks to the public API using an automation key. PRD mcp-course-authoring [DONE].
• User flow: Configure MCP client with API key → AI tools create/update courses.

3.24 Enterprise SSO & Token Auth (licensed)

• Purpose: OIDC SSO and token‑based auth for enterprise self‑host.
• How it works: apps/api/src/routes/organization/sso.ts, apps/api/src/routes/sso/discovery.ts (mounted /organization/sso, /sso, app.ts:211,213); organizationSsoConfig (schema.ts:2479), provider enum OKTA|GOOGLE_WORKSPACE|AUTH0 (schema.ts:2444), organizationAuthPolicy (2447). Token auth: apps/api/src/routes/organization/token-auth.ts, organizationTokenAuth (2513). License‑gated on self‑host via requireLicense('sso'|'token-auth') (apps/api/src/middlewares/license.ts). PRD enterprise-sso [DONE].
• User flow: Org → SSO settings → register IdP (discovery fetches .well-known/openid-configuration) → users sign in via IdP.
• Edge cases: trusted OIDC origins allow‑listed (packages/db/src/constants.ts:14–24); cloud has no license restriction (see §5).

3.25 Licensing

• Purpose: gate Enterprise self‑host features behind a license key.
• How it works: apps/api/src/routes/license.ts (mounted /license, app.ts:209), apps/api/src/services/license.ts (isFeatureLicensed), feature ids sso, token-auth, no-tracking (packages/utils/src/license/constants.ts:8–10), plan→feature mapping packages/utils/src/license/plan-features.ts. Dashboard side apps/dashboard/src/lib/features/license/api/license.svelte.ts (licenseApi.hasAccess).
• User flow: Set LICENSE_KEY (.env.example:117–118) → licensed features unlock.
• Edge cases: requireLicense is a no‑op on cloud (license.ts:15–19).

3.26 Billing (Polar) — cloud

• Purpose: paid subscriptions and AI token packs.
• How it works: apps/dashboard/src/routes/api/polar/{subscribe,buy-tokens,portal,webhook}. Webhook handles order.paid (token packs → credit balance) and subscription.* (create/update/cancel org plan). webhook/+server.ts → 30–168. Plans enum EARLY_ADOPTER|ENTERPRISE|BASIC (schema.ts:28), org plan stored in organizationPlan (schema.ts:1667).
• User flow: Upgrade → Polar checkout → webhook activates/updates plan; manage via portal.
• Edge cases: cloud only; subscription cancel → cancelOrgPlan; webhook secret POLAR_WEBHOOK_SECRET required.

3.27 Analytics

• Purpose: usage analytics for orgs/courses.
• How it works: apps/api/src/routes/dash + apps/api/src/services/analytics; tables analyticsLoginEvents, analyticsPageEvent, analyticsOrgDaily, analyticsCourseDaily, analyticsCountryDaily (schema.ts:167–285). Dashboard apps/dashboard/src/lib/features/analytics. Client tracking (PostHog/Umami) gated by deployment mode / license (§5).
• User flow: Org → Analytics dashboard → view login/page/course metrics.

3.28 Email / Notifications & Background Jobs

• Purpose: transactional email and async processing.
• How it works: apps/api/src/routes/mail, templates in packages/email, enqueued via enqueueTransactionalEmail (apps/api/src/services/jobs, onboarding.ts:128). Workers in apps/jobs; BullMQ dev dashboard at /admin/queues (apps/api/src/routes/admin/queues.ts, app.ts:232–234). Email providers: Zoho/ZeptoMail or SMTP (.env.example:62–74).
• User flow: trigger (signup, invite, completion) → email queued → worker sends.
• Edge cases: idempotency keys (onboarding.ts:133); dead‑letter jobs (schema.ts:3447).
• Note: an in‑app notification system is prd/notification-system todo — not shipped.

---

4. Roles & Responsibilities

Org roles are integers: ADMIN=1, TUTOR=2, STUDENT=3 (packages/utils/src/constants/roles.ts:1–4). They are stored on organizationmember.roleId (schema.ts:1767, FK to role table schema.ts:1913) and surfaced into the session as an orgRoles map keyed by org id (apps/api/src/app.ts:88). RBAC middlewares read orgRoles[orgId] (org id from the cio-org-id header) — no per‑request DB lookup (apps/api/src/middlewares/org-team-member.ts:5–53).

Role	Can do	Cannot do	Enforced by
ADMIN (1)	Full org control: settings, members, billing, courses, SSO, API keys, all team actions	—	org-admin.ts, org-team-member.ts (admin∈team)
TUTOR (2)	Team actions: author/manage courses, grade, moderate community/newsfeed	Org admin‑only ops (org settings, billing, member roles)	org-team-member.ts:44 (ADMIN or TUTOR), course-team-member.ts
STUDENT (3)	Enroll, learn, submit exercises, post community Q&A, use tutor	Authoring/grading/team/admin actions	absence of team/admin role → 403
Guest / anonymous	Public org sites, public courses, embeds, public API (with key)	Any authed action	session = null path (app.ts:77–84); public CORS paths (app.ts:60–67)

Resource‑scoped middlewares (apps/api/src/middlewares/):

• authMiddleware — requires a session (auth.ts).
• orgMemberMiddleware — must be org member; orgTeamMemberMiddleware — ADMIN|TUTOR; orgAdminMiddleware — ADMIN only (ARCHITECHTURE.md:233–237).
• courseMemberMiddleware / courseTeamMemberMiddleware — course‑level membership/team.
• cohortMemberMiddleware / cohortTeamMemberMiddleware — cohort-level.
• apiKeyMiddleware / automationKeyMiddleware (+ automationKeyScopesMiddleware) — machine auth for webhooks/public API; authOrApiKeyMiddleware, authOrAutomationKeyMiddleware, and *-or-automation-key/*-or-api-key variants allow either a session or a key.
• requireLicense(feature) — self‑host license gate (license.ts).
• workspaceNotReadonlyMiddleware — blocks writes on read‑only workspaces (workspace-not-readonly.ts).
• signupGuard — signup rules (§3.2). rateLimiter — global rate limit (app.ts:98).
• Route‑specific author/team guards: question-author-or-team, newsfeed-comment-author-or-team, cohort-newsfeed-comment-author-or-team.

Public API scopes: automation keys carry scopes like public_api:*, enforced per route (apps/api/src/routes/v1/courses.ts:47); usage categorized read|write|publish (schema.ts:32).

---

5. Deployment Modes — Self‑Hosted vs Cloud

The single switch is PUBLIC_IS_SELFHOSTED (=true ⇒ self‑hosted). Source of truth: .env.example:26 (Docker stack), apps/dashboard/.env.example, and the local‑dev value apps/dashboard/.env (PUBLIC_IS_SELFHOSTED=true, README.md:155). The flag is read in both the API/db layer (process.env.PUBLIC_IS_SELFHOSTED) and the dashboard ($env/static/public). Every behavioral difference below is traced to a flag check.

5.1 Self‑Hosted mode (PUBLIC_IS_SELFHOSTED=true)

• Setup: Docker Compose full stack — cp .env.example .env then ./run-docker-full-stack.sh (auto‑generates PRIVATE_SERVER_KEY, BETTER_AUTH_SECRET); README.md:240–249, docker-compose.yaml, docker/Dockerfile.{api,dashboard}, docker/docs/SELF_HOST.md. Bundled Postgres, Redis, MinIO.
• Single organization: org creation blocks a second org (apps/api/src/services/onboarding.ts:28–33); the new org is auto‑assigned an ENTERPRISE plan with provider selfhosted (onboarding.ts:64–77). The "add org" UI is hidden (apps/dashboard/src/routes/(app)/org/[slug]/+layout.svelte:29–31) and the org‑site→LMS redirect is skipped (.../+layout.server.ts:16). PRD self-host-single-org.md.
• Signup: requires org context unless bootstrapping the first org or the email already belongs to the org (signup-guard.ts:75–91).
• Licensing: Enterprise features (sso, token-auth, no-tracking) are gated by LICENSE_KEY — requireLicense actively checks (middlewares/license.ts:15–22); .env.example:117–118.
• Tracking: cloud analytics (PostHog/Umami) are disabled (apps/dashboard/src/lib/utils/functions/appSetup.ts:23–27); a no-tracking license also suppresses tracking (appSetup.ts:29–37).
• URLs/links: BASE_URL and invite/email links use DASHBOARD_ORIGIN when self‑hosted (packages/db/src/constants.ts:36–37; .env.example:32–35). Dashboard SSR calls the API internally via PRIVATE_SERVER_URL (.env.example:28–30).
• Storage/email: MinIO + Zoho/SMTP from .env (.env.example:62–89).

5.2 Cloud mode (PUBLIC_IS_SELFHOSTED ≠ true)

• Multi‑org: users can create/switch multiple orgs (no single‑org block); "add org" UI shown (+layout.svelte:29).
• Billing: Polar subscriptions + AI token packs are active (apps/dashboard/src/routes/api/polar/*); plan set via subscription webhooks (webhook/+server.ts). License gate is a no‑op — cloud has no license restrictions (middlewares/license.ts:15–19).
• Tracking: PostHog/Umami/UserJot analytics enabled (appSetup.ts:17–27).
• Signup: org context optional unless org settings restrict it (signup-guard.ts:132–139).
• Infra: hosted Postgres/Redis/S3; dashboard deployed on Cloudflare Workers (apps/dashboard/wrangler.jsonc, svelte.config.js).

5.3 Mode‑exclusive features (summary)

Concern	Self‑Hosted	Cloud
Number of orgs	One only (onboarding.ts:28)	Many
Enterprise SSO / token‑auth	Requires LICENSE_KEY (license.ts)	Always allowed (no license)
Billing (Polar)	Not used (plan = selfhosted ENTERPRISE)	Subscriptions + token packs
Analytics tracking	Off (unless… still off) (appSetup.ts:24)	On
API base / links	DASHBOARD_ORIGIN (constants.ts:37)	PUBLIC_SERVER_URL
Add‑org modal	Hidden (+layout.svelte:29)	Shown

Both modes exist in source and share one codebase; neither mode is ⚠️ NOT FOUND. The product is one app with flag‑driven divergence.

---

6. End‑to‑End Flow Diagrams (text)

A. Signup → Onboarding → Workspace

Login/Signup (apps/dashboard/.../(auth)/signup)
  → POST /api/auth/sign-up/*  [signupGuard]      (app.ts:106; signup-guard.ts)
  → Better Auth creates user + profile           (auth.ts; create-profile.ts)
  → (auth)/onboarding: createOrganizationWithOwner (onboarding.ts:19)
        · self-host: block 2nd org, assign ENTERPRISE plan
  → completeOnboarding → enqueue 'welcome' email (onboarding.ts:121)
  → Dashboard /lms or /org/[slug]

B. Author a course

Courses → New course (course.ts)
  → add sections (section.ts) → lessons (lesson.ts) + translations (lesson-language.ts)
  → add exercises/questions (exercise.ts, question-types)
  → [optional] AI Assistant builds content (agent/*; requires provider key)
  → publish → appears on org site / widget

C. Student learns → certificate (compliance)

Invite (course/invite.ts) → accept /invite/[hash]
  → enroll (people.ts) → study lessons → mark complete (lessonCompletion)
  → submit exercises (submission.ts) → tutor grades (mark.ts)
  → completion recorded (courseCompletionRecord schema.ts:768)
  → certificate issued (packages/certificates; courseCertificateIssue schema.ts:850)
  → compliance: deadlines/renewals tracked (course/compliance.ts; internal/*)

D. Public API automation (integration)

Org → create automation key with scopes (organization/automation.ts; organizationApiKey)
  → external client: GET/POST /public-api/v1/courses
        [automationKeyMiddleware + automationKeyScopesMiddleware('public_api:*')]
  → service resolves orgId from key → returns course data (v1/courses.ts; services/v1)

E. Cloud upgrade / buy AI tokens (cloud only)

Upgrade or Buy tokens (api/polar/subscribe | buy-tokens)
  → Polar checkout
  → Polar webhook (api/polar/webhook/+server.ts)
        · subscription.created → createOrgPlan
        · order.paid (token_pack) → recordPurchase → aiCreditBalance

---

7. Open Questions & Gaps

1. Outbound webhooks — doc vs code mismatch. README.md:42–43 advertises "REST API + Webhooks … receive events (certificate.issued, enrollment.completed)", but the only webhook code is inbound Polar billing (apps/dashboard/src/routes/api/polar/webhook) and prd/webhooks is todo (PRD-TRACKER.md:24). No outbound event‑emission/delivery system was found in apps/api/src or packages/db/src. Code wins: outbound webhooks appear unimplemented. QA should not test event delivery as a shipped feature. ⚠️
2. SCORM support — README does not promise it, but prd/scorm-support is todo (PRD-TRACKER.md:16). No SCORM code located. ⚠️ Treat as not shipped.
3. In‑app notification system — prd/notification-system is todo (PRD-TRACKER.md:9). Transactional email exists (§3.28); in‑app notifications appear unbuilt. Verify before demoing. ⚠️
4. Selective exercise assignment — prd/selective-exercise-assignment is todo (PRD-TRACKER.md:15). Assigning specific exercises to specific students may not exist; confirm against exercise.ts behavior. ⚠️
5. Course templates / cohorts / import variants — prd/course-templates, prd/course-cohorts, prd/course-import are todo (PRD-TRACKER.md:10,12,13), yet related schema exists (exerciseTemplate schema.ts:2401; courseImportDraft schema.ts:2603; cohorts are DONE). Scope of what's actually wired end‑to‑end vs. schema‑only should be verified per feature before writing test cases. ⚠️
6. Anthropic in AI picker — code supports Anthropic, but it is "not currently in the picker UI" (README.md:231, .env.example:112). The picker exposes Gemini + GPT‑4o; note the .env.example:111 "Gemini 3 Flash" vs README.md:228 "Gemini 2.5 Flash" wording inconsistency — verify the actual model id in packages/utils/src/agent-models.
7. Two operating sub‑modes within self‑host (single‑org bootstrap vs. licensed Enterprise) interact with signupGuard and requireLicense. Exact UX when LICENSE_KEY is absent on self‑host (SSO/token‑auth hidden vs. 403) should be confirmed in the dashboard license feature before recording a self‑host SSO demo.
8. Tenant‑router / domain routing (apps/tenant-router, /domain) was inventoried but not deeply traced (infra scope). Custom‑domain happy‑path is PRD‑DONE; failure/SSL provisioning states are unverified here.

---

Appendix — Supporting Infrastructure (light)

These exist in source but are infra/dev tooling rather than demoable product features:

• apps/jobs — BullMQ worker process; consumes media/email queues (paired with apps/api/src/routes/jobs, mediaJob/jobStep tables). Dev queue UI at /admin/queues (apps/api/src/routes/admin/queues.ts).
• apps/tenant-router — multi‑tenant/custom‑domain request routing (backs §3.20).
• apps/course-app / packages/course-app — course‑app runtime modules (pnpm-workspace.yaml:4).
• apps/docs — documentation site (pnpm docs:dev).
• apps/website — marketing site (pnpm website:dev).
• packages/core — shared config incl. env access (packages/core/src/config/env.ts, used by signup-guard.ts, license.ts, onboarding.ts).
• packages/storybook — UI component stories (pnpm storybook:dev).
• packages/analytics — analytics helpers (paired with apps/api/src/services/analytics).
• packages/tsconfig — shared TS config.
• packages/ui — shared Svelte component library (@cio/ui); theme classes require ui: prefix in dashboard (AGENTS.md:313).
• packages/utils — shared Zod validation, plans, license, agent‑models, constants.
• packages/db — Drizzle schema/queries/migrations/seed; pnpm --filter @cio/db db:setup:seed seeds demo data and the demo login admin@test.com / 123456 (README.md:215–219).

---

How this audit was verified

Every section traces to files read during the audit: README.md, ARCHITECHTURE.md, AGENTS.md, .env.example, PRD-TRACKER.md, apps/api/src/app.ts, packages/db/src/schema.ts, the role/RBAC middlewares, signup-guard.ts, onboarding.ts, appSetup.ts, the Polar webhook, the v1 public‑API router, and the license constants/middleware. No application was run and no tests were executed — functional testing is deferred to the QA phase per the audit brief.