internal active Last verified 2026-04-09

TopoloLearn Handbook

Internal handbook for TopoloLearn control-plane, studio, branded runtime, member, assessment, certification, and enterprise-seat surfaces.

Owners
product-platform
Source Repos
PlatformApplications/TopoloLearn, PlatformApplications/TopoloDocs
Systems
Topolo Auth, TopoloLearn, Topolo Platform
Tags
learning, cohorts, assessment, certificates

What It Is

TopoloLearn is the Topolo-native learning platform for branded education businesses and enterprise-enabled cohort delivery. It is designed to support both creator-led and organization-led learning products without forking the application by customer.

Architecture

TopoloLearn is structured as a multi-tenant Cloudflare-native application with one browser runtime, one Worker API, a shared D1 data model, published brand snapshots, and product-local role enforcement layered on top of Topolo Auth identity.

The current browser runtime is no longer a thin overview scaffold. It now uses:

  • a canonical Topolo internal shell for operator, studio, and member surfaces
  • the product-facing browser identity Learn, even though the system and repo remain TopoloLearn
  • route-specific page modules instead of one generic page per surface
  • route-scoped API contracts for operator, studio, member, runtime, activity, assessment, and certificate work
  • shared Topolo app-switcher and bug-reporting primitives from @topolo/ui-kit
  • shared first-party icon assets and browser metadata so favicon, launcher, and share previews all resolve to the Learn iconography
  • a dedicated studio/pages route for public runtime copy, faculty, and FAQ management

Runtime Surfaces

  • PlatformApplications/TopoloLearn/apps/web
  • PlatformApplications/TopoloLearn/apps/api
  • PlatformApplications/TopoloLearn/packages/domain
  • PlatformApplications/TopoloLearn/packages/config
  • PlatformApplications/TopoloLearn/packages/database

API Reference

The current API worker exposes:

  • GET /health
  • GET /runtime/resolve
  • GET /operator/summary
  • GET /operator/tenants
  • GET /operator/tenants/:tenantId
  • GET /operator/brands
  • GET /operator/audit
  • GET /studio/dashboard
  • GET /studio/brand
  • PATCH /studio/brand
  • GET /studio/programmes
  • POST /studio/programmes
  • GET /studio/programmes/:programmeId
  • POST /studio/programmes/:programmeId/modules
  • GET /studio/cohorts
  • POST /studio/cohorts
  • POST /studio/cohorts/:cohortId/live-sessions
  • GET /studio/assessments
  • GET /studio/assessments/:submissionId
  • GET /studio/evidence-pack
  • GET /studio/certificates
  • GET /studio/companies
  • POST /studio/companies
  • GET /studio/contacts
  • GET /studio/domains
  • POST /studio/domains
  • GET /studio/team
  • GET /studio/analytics
  • GET /studio/settings
  • GET /studio/activity
  • GET /member/dashboard
  • GET /member/programmes
  • GET /member/programmes/:programmeId
  • GET /member/modules/:moduleSlug
  • GET /member/artefacts/:artefactSlug
  • POST /member/artefacts/:artefactSlug/submissions
  • GET /member/evidence-pack
  • GET /member/feedback
  • GET /member/live/:sessionId
  • GET /member/certificates
  • GET /member/settings
  • GET /member/activity
  • POST /assessments/submissions/:id/review
  • POST /certificates/:id/issue
  • GET /certificates/verify/:code

Product Areas

  • operator control plane
  • tenant studio
  • branded public runtime
  • branded member runtime
  • assessment engine
  • certificate and verification surfaces
  • enterprise seat management

Auth and Permissions

TopoloLearn uses the shared browser auth contract in PlatformApplications/packages/topolo-auth-client and the shared Worker validation middleware in PlatformApplications/packages/topolo-auth-middleware.

Topolo Auth remains authoritative for:

  • user identity
  • organization context
  • session validity
  • first-party service registry metadata
  • app-switcher visibility and product routing

TopoloLearn owns tenant- and brand-local role assignment inside its own domain model. The worker resolves the authenticated tenant from Topolo Auth first and rejects mismatched tenant requests before any repository read or write proceeds.

Studio access is granted from either:

  • Learn-native tenant roles such as tenant_admin, brand_admin, editor, instructor, assessor, and enterprise_manager
  • Auth-managed generic admin roles such as admin
  • Auth service permissions for Learn such as studio:read, studio:write, programmes:*, assessments:*, certificates:*, and settings:*

Operator routes now hard-require platform-level roles in the Worker. Studio and member routes are tenant-scoped in the Worker even when the browser shell renders first.

Platform staff do not silently inherit a seeded tenant or brand in studio. If a platform role reaches the studio without an active tenant context, the browser requires an explicit brand selection before route data loads.

Data Ownership

TopoloLearn owns tenant, brand, learning, assessment, certificate, enterprise-seat, audit, and analytics state inside its own D1 model. Topolo Auth remains the source of truth for identity, session validation, service registry metadata, and cross-product browser handoff.

Isolation Model

The current v1 isolation model uses a shared D1 database with explicit tenant and brand scopes on every business record.

Rules:

  • every business table carries tenant_id
  • brand-owned tables carry brand_id
  • hostname resolution returns a published runtime payload before the UI renders public or member context
  • operator, studio, and member route handlers resolve the authenticated tenant before choosing a brand scope
  • repository helpers accept explicit tenant scope and do not allow free-form cross-tenant access

This keeps the first release operationally simple while preserving a clear future split path for premium or regulated tenants.

Brand Runtime Model

Each brand can publish:

  • a default platform hostname
  • zero or more mapped custom domains
  • a public site surface
  • a member portal surface
  • a brand theme snapshot containing color, typography, density, button, card, and certificate tokens

The public and member experiences share the same underlying brand configuration but can expose different navigation and content routes.

The current browser rebuild keeps internal surfaces inside the shared Topolo shell while allowing only the public runtime and narrow member accents to reflect tenant brand identity.

The internal shell no longer derives its visible identity from hostname-resolved brand fallback data. Studio and operator surfaces stay platform-neutral even when the runtime bootstrap payload contains brand records for scope selection.

The current studio implementation now supports:

  • full brand token editing for color, typography, density, button, card, and certificate frame settings
  • navigation and footer-link editing for the published runtime
  • public runtime copy editing for hero, enterprise, about, apply, faculty, and FAQ content
  • hostname creation for public and member surfaces inside the studio
  • programme, module, cohort, and live-session creation flows
  • enterprise account creation with initial seat-pack setup
  • learner seat assignment from existing enterprise inventory

The current member implementation now supports:

  • artefact submission and resubmission directly from the learner route
  • submission version creation without dropping into a generic file admin surface
  • immediate review-state reset and evidence-pack recalculation after a learner submits a new version

Assessment And Certification

Assessment is a first-class domain area rather than an add-on.

  • artefact requirements can attach to programmes or modules
  • submissions keep version history
  • assessors record rubric-backed outcomes
  • evidence packs aggregate approved artefacts
  • certificates can be issued only when programme gating rules are met
  • certificate verification is public and route-based

Enterprise Model

Enterprise support is part of the first domain cut:

  • organizations buy seat packs
  • seat packs can be tied to a cohort
  • seats can be assigned by name and email before activation
  • enterprise managers have a tenant-local management role rather than platform-level admin access

Deployments

TopoloLearn declares a Pages web surface plus an API Worker in CloudControl. The current runtime uses D1-backed read and mutation paths where a database binding is present and falls back to seeded in-memory catalog data for local or bootstrap scenarios where the Worker does not have D1 available yet.

Failure Modes

  • missing brand-domain mappings prevent hostname boot
  • missing or invalid Topolo Auth session state blocks studio and member access
  • unprovisioned Cloudflare binding ids block real persistence until environment setup is completed

Debugging

Check the runtime entrypoints in apps/web/src/App.tsx and apps/api/src/index.ts, then verify the D1 migration, Worker bindings, and CloudControl manifest. Use the specialized blueprint, technical architecture, schema, and operations docs for deeper subsystem detail.

Change Log / Verification

  • Corrected studio scope and internal shell behavior on 2026-04-09 so super_admin can access studio routes, platform users must explicitly choose a brand scope before studio data loads, and internal surfaces stop displaying seeded tenant branding from runtime fallback data
  • Added persisted public runtime content editing and learner-side artefact submission on 2026-04-08, including the studio/pages route, POST /member/artefacts/:artefactSlug/submissions, D1-backed site_content_json persistence, and live runtime consumption of edited copy blocks
  • Expanded the studio contract on 2026-04-08 so brand builder now manages richer theme/navigation state, the studio can create domain mappings and enterprise accounts, and the Worker exposes matching write endpoints for programme/module/cohort/session/domain/company flows instead of read-only route surfaces
  • Rebuilt the Learn browser runtime and Worker contract on 2026-04-08 so operator, studio, member, and public surfaces now use a Topolo-native shell, dedicated route modules, route-scoped API resources, activity inboxes, command access, and D1-aware repository loading instead of the earlier overview-page scaffold and demo-store-only contract
  • Added the initial canonical handbook, architecture, schema, and operations coverage for TopoloLearn on 2026-04-08.
  • Added the first TopoloLearn workspace scaffold, schema plan, CloudControl manifest, and shared Topolo Auth/AppLauncher integration points on 2026-04-08.