TopoloLearn

What It Is

TopoloLearn is the Topolo application for branded learning businesses. It combines a public site, member portal, learn account studio, assessment workflows, evidence packs, certificates, and customer seat management in one multi-brand product.

Architecture

TopoloLearn is split across:

• a web application for operator, studio, public, and member experiences
• a Worker API for Learn account-safe reads, writes, and verification routes
• D1, R2, KV, and queues for learning, submission, certificate, and published-brand state

The first-party learn.topolo.app homepage uses the shared Topolo landing-page package and Auth-managed landing config. Authenticated visitors can continue directly from the landing CTA or /login into Learn's application home. Learn account brand hostnames use Learn's product runtime to render brand-owned public pages, programme detail, offers, faculty, FAQ, and member entrypoints.

Workspace Management

The shared Topolo workspace control reads and manages app-scoped workspace identity through Topolo Auth: authenticated users can list, create, rename, choose a default, and delete an eligible workspace. Workspace IDs and slugs remain stable and exactly one default is explicit. The selected platform workspace scopes this application's app-owned records; the app retains only domain-specific deletion guards for default or non-empty workspaces.

For Learn, the platform workspace id is also the brand id. Learn owns the learning and presentation data attached to that id, while Auth remains the sole owner of its workspace name, slug, and default status.

Runtime Surfaces

• apps/TopoloLearn/apps/web
• apps/TopoloLearn/apps/api
• Topolo Auth for identity, session validation, and app-switcher metadata

API Reference

The initial curated API surface lives in apps/TopoloLearn/apps/api/src/index.ts and currently includes runtime resolution, operator and studio overview, learner overview, submission review, certificate issuance, and public verification routes.

Multi-Brand Model

TopoloLearn is a platform product rather than a single-customer LMS.

• one TopoloLearn deployment serves multiple Auth organization-owned Learn accounts
• each learn account can own multiple brands
• each brand can publish its own public and member hosts
• all application data is learn account-scoped and brand-aware

Core Feature Areas

• branded public websites
• branded member portals
• learn account studio for theme, programme, cohort, assessment, and certificate management
• artefact submissions with versioning
• rubric-based review flows
• evidence pack assembly
• certificate issuance and public verification
• customer seat packs and assignment

Demo Learn account

The seed data uses a neutral customer-academy demo account to exercise cohort-heavy certification flows without hardcoding TopoloLearn around any real business.

Auth and Permissions

TopoloLearn uses Topolo Auth for identity and session state, with browser login handoff and callback-code redemption delegated to the shared Topolo Auth client. API bearer requests are validated by Topolo Auth before product-specific learn account and brand roles are enforced inside the Learn worker, so authenticated users only reach the operator, studio, or member surfaces allowed by their TopoloLearn role assignments. Improve Topolo is exposed through the shared authenticated account menu rather than standalone header or command-palette controls.

Data Ownership

TopoloLearn owns learn account, Learn-specific brand configuration, programme, cohort, assessment, submission, evidence-pack, certificate, and customer-seat state. Topolo Auth remains authoritative for user identity, organization context, and app-scoped workspace identity.

Mobile Experience

The checked-in mobile experience contract is published in native_capability mode. Its fallback route is /programmes, its offline policy is read_through_cache, and it requires organization context.

Published permissions: studio:read, studio:write, certificates:write, operator:read, settings:read, runtime:read.

• /programmes uses /api/studio/programmes with the record.list template and learn.programmes.list data source.
• /programmes/:id uses /api/studio/programmes/:id with the record.detail template and learn.programmes.detail data source.
• /assessments uses /api/studio/assessments with the record.list template and learn.assessments.list data source.
• /assessments/:id uses /api/studio/assessments/:id with the record.detail template and learn.assessments.detail data source.
• /cohorts uses /api/studio/cohorts with the record.list template and learn.cohorts.list data source.
• /customers uses /api/studio/customers with the record.list template and learn.customers.list data source.

The native clients consume this manifest as an explicit rendering contract. A web mode record intentionally opens the product web experience; native_capability publishes the listed native routes and actions. Do not infer unlisted native behavior.

Deployments

TopoloLearn currently defines a web Worker surface plus a Worker API surface with Cloudflare D1, R2, KV, and queue bindings declared in the CloudControl manifest. The staging mirror uses https://learn.stg.topolo.us and https://learn-api.stg.topolo.us; staging web builds run with staging Auth/API origin injection and a staging-only rewrite for shared UI defaults that would otherwise emit production origins.

Failure Modes

• hostname resolution can fail when a brand has no published domain mapping
• authenticated studio or member routes can fail when Topolo Auth session validation is unavailable
• certificate issuance should remain blocked until evidence-pack and assessment gating rules are satisfied

Debugging

Start with the internal handbook at /internal/apps/topolo-learn, then inspect apps/api/src/index.ts, the D1 migration set, and the CloudControl manifest for route, schema, and deployment shape.

Use It

Open TopoloLearn for the human product surface. The system handbook records its current hosts, ownership, Auth scopes, storage, deployment, failure modes, and machine artifact.

Discover the credential-scoped automation surface before making an API call:

topolo services --query topolo-learn --json
topolo actions --service topolo-learn --json
topolo actions capabilities --service topolo-learn --json

Choose an action, inspect it with topolo actions get <action-id> --json, then validate and plan a published example. The Agent Actions reference exposes the same public schemas, effects, examples, verification, and recovery guidance.

Example workflow:

1. Confirm the active identity and organization with topolo whoami --json.
2. Discover TopoloLearn and select one published action rather than guessing a route.
3. Inspect its input/output schemas and published example.
4. Validate and plan the exact payload; obtain confirmation for a mutation.
5. Execute and perform every published verification step.

Change Log / Verification

• Reconciled the platform-owned workspace model through apps/TopoloLearn origin/staging 6975b471c881 on 2026-07-28. Learn no longer stores an independently writable copy of the workspace name, slug, or default state.

• Verified the native_capability mobile experience contract and its 6 published route(s) against apps/TopoloLearn origin/staging 16a07b42aa87 on 2026-07-27.

• Reconciled this page against apps/TopoloLearn origin/staging 0aa8b66a4bb9 on 2026-07-24 after reviewing every docs-relevant commit since its previous verification watermark. Dependency-only currency commits were checked by the fleet production-dependency gate and did not change this page's product contract.

• Reconciled workspace verification on 2026-06-28 against apps/TopoloLearn commits through 83b9837; reviewed 97 commits since 2026-06-18, including 83b9837 Use shared Studio UI primitives in Learn; 73a525b Split Learn cohort studio sections; 727a860 chore(deps): refresh @topolo-io/app-shell pins (package.json + lockfile); 98765dd Use shared ui kit for Learn surfaces.

• Moved visible Learn Improve Topolo access fully into the shared account menu on 2026-05-12.

• Verified Learn staging origin isolation on 2026-04-30.

• Verified on 2026-04-18 that Learn API bearer validation requires Topolo Auth validation before Learn-local role enforcement.

• Delegated Learn web login handoff and callback-code redemption to the shared Topolo Auth client on 2026-04-18.

• Verified on 2026-04-17 that authenticated visitors route from the shared Learn landing entrypoint into the application home instead of re-opening login.

• Verified on 2026-04-16 that the first-party Learn platform homepage uses the shared landing page while learn account brand pages remain Learn-owned runtime pages.

• Added the initial public overview for TopoloLearn on 2026-04-08.

• Verified the doc against the new application scaffold, shared auth integration points, and TopoloLearn system entry on 2026-04-08.