TopoloLearn Product Blueprint | Topolo Internal Handbook

What It Is

This page is the product and architecture blueprint for TopoloLearn. It captures the business framing, tenancy model, route map, user types, security boundaries, and the future-facing decisions behind the first platform cut.

Architecture

TopoloLearn is a multi-tenant Topolo application that separates control-plane, studio, public runtime, member runtime, assessment, and certificate concerns while reusing shared Topolo identity and browser-shell conventions.

Runtime Surfaces

control-plane and operator tooling
tenant studio
branded public runtime
branded member runtime
assessment and certificate workflows

API Reference

The concrete route handlers live in the Worker handbook and code, but this blueprint defines the product contract those routes must serve: tenant-safe management APIs, runtime-resolution endpoints, assessment lifecycle endpoints, and certificate verification and issuance flows.

Product Framing

TopoloLearn is the platform. Customers are tenants. Tenants can run one or more brands. Each brand can publish a distinct public site and member portal while sharing the tenant’s core learning, team, and enterprise operations.

User Types

platform operators
tenant owners and tenant admins
brand admins and editors
instructors and assessors
enterprise managers
learners
public prospects and applicants

Roles

Platform roles:

platform owner
platform admin
support
operator

Tenant and brand roles:

tenant owner
tenant admin
brand admin
editor
instructor
assessor
enterprise manager
learner

Tenancy Model

tenant is the business boundary for billing, plan, and top-level access
brand is the runtime and presentation boundary
brand_domain maps hostnames to public or member surfaces
tenant_membership maps users into tenant-local roles
future dedicated infrastructure isolation is possible by moving one tenant’s repositories to a separate binding set

Brand Model

Each brand owns:

public and member hostnames
theme tokens
navigation and footer structure
SEO and social metadata
certificate styling tokens
published programmes, offers, and cohorts

Feature Modules

control plane for tenants, brands, plans, and flags
tenant studio for themes, domains, programmes, offers, cohorts, assessment, certificates, and analytics
branded public runtime
branded member runtime
assessment engine
evidence pack engine
enterprise seats and invitations
certificate issuance and verification

Route Map

Operator:

/operator
/operator/tenants
/operator/tenants/:tenantId
/operator/brands
/operator/support
/operator/audit

Studio:

/studio
/studio/brands
/studio/brands/:brandId
/studio/brands/:brandId/theme
/studio/programmes
/studio/programmes/:programmeId
/studio/cohorts
/studio/assessments
/studio/certificates
/studio/domains
/studio/team
/studio/analytics

Public runtime:

/
/programmes
/programmes/:slug
/offers/:slug
/enterprise
/apply
/about
/faculty
/login

Member runtime:

/app
/app/programmes
/app/cohorts/:cohortId
/app/modules/:moduleSlug
/app/artefacts/:artefactSlug
/app/evidence-pack
/app/live/:sessionId
/app/feedback
/app/certificates
/app/settings

Auth and Permissions

Topolo Auth owns identity, session validity, and cross-product routing metadata. TopoloLearn maps authenticated identities into tenant-local and brand-local roles and must enforce those roles before any data access or management action.

Data Ownership

TopoloLearn owns:

tenant, brand, theme, domain, and programme metadata
cohorts, lessons, live sessions, and offers
enrolments, submissions, reviews, evidence packs, and certificates
enterprise organizations, seat packs, and seat assignments
audit and analytics events

Topolo Auth owns:

user identity
service registry
session validity
org context for authenticated requests

Deployments

This blueprint assumes one shared TopoloLearn deployment that serves many tenants while preserving explicit tenant and brand scoping in the runtime and persistence layers.

Failure Modes

role assignment gaps can leave authenticated users without the expected studio or member access
incorrect hostname mappings can boot the wrong runtime surface for a brand
incomplete assessment state can incorrectly delay certificate readiness if gating rules are modeled inconsistently

Debugging

Use this blueprint to confirm intended behavior first, then verify the matching runtime and schema docs before changing the worker or browser surfaces.

Runtime Boundaries

the web app renders all browser-facing route groups
the Worker API is the only writer for persistent learning data
D1 owns relational state
R2 owns uploads and generated certificate assets
KV owns published brand snapshots and fast verification aids
queues own asynchronous analytics and long-running background jobs

Background Jobs

Queued and workflow-backed jobs are reserved for:

certificate rendering and delivery
reminder and cohort lifecycle messaging
evidence pack completion checks
analytics fan-out
future AI-assisted review flows

Security Model

authenticated routes depend on Topolo Auth
tenant scope is derived from Auth before request data is trusted
public forms are intended to use Turnstile at the brand surface
certificate verification is public but read-only and code-scoped

Future Extensibility

The model explicitly leaves room for:

AI-assisted learning and review
advanced billing and plan entitlements
richer CRM and automation layers
stronger tenant isolation
partner and licensing models

Change Log / Verification

Added the initial TopoloLearn blueprint covering tenancy, roles, route map, data ownership, runtime boundaries, and future extensibility on 2026-04-08.