internal active Last verified 2026-04-09

TopoloLearn Technical Architecture

Technical architecture for the TopoloLearn monorepo, bindings strategy, hostname resolution, caching, and observability.

Owners
product-platform
Source Repos
PlatformApplications/TopoloLearn, PlatformApplications/TopoloDocs
Systems
TopoloLearn
Tags
learning, architecture, cloudflare

What It Is

This page captures the implementation-facing technical architecture for TopoloLearn: workspace layout, shared packages, Cloudflare bindings, hostname resolution, caching, and observability.

Architecture

TopoloLearn uses a small monorepo with one browser app, one Worker API, and focused shared packages for domain types, config, and database assets. Shared Topolo auth and UI packages remain external dependencies rather than product-local forks.

The current browser rebuild now aligns to the canonical Topolo shell pattern instead of a custom tenant-branded admin frame. Operator, studio, and member route groups render inside one neutral first-party shell while the public runtime remains branded.

Runtime Surfaces

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

API Reference

The technical contract centers on one Worker API surface in apps/api/src/index.ts and one browser runtime in apps/web/src/App.tsx. The worker now owns runtime-resolution plus route-scoped operator, studio, member, activity, assessment, and certificate routes instead of only three overview endpoints.

The studio surface now includes mutation endpoints for:

  • brand token and navigation updates
  • public runtime copy, faculty, and FAQ updates through the shared brand/page contract
  • programme and module creation
  • cohort and live-session creation
  • enterprise account provisioning
  • seat assignment
  • domain mapping

Workspace Structure

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

Shared Package Usage

TopoloLearn is expected to reuse:

  • PlatformApplications/packages/topolo-auth-client
  • PlatformApplications/packages/topolo-auth-middleware
  • PlatformApplications/packages/topolo-ui-kit
  • PlatformApplications/packages/topolo-design-tokens

The first-party app registry in @topolo/ui-kit is the canonical browser-shell identity surface for app-switcher rendering, icons, and auth/loading transitions.

Learn browser assets now also flow through the shared @topolo/ui-kit icon pipeline so favicon, Apple touch, and share-preview assets stay aligned with the same first-party glyph and accent system used by the app launcher.

Internal Dependencies

  • the web app depends on domain, config, database, @topolo/auth-client, and @topolo/ui-kit
  • the API depends on domain, config, database, and @topolo/auth-middleware
  • domain stays free of runtime-only infra bindings

Cloudflare Bindings Strategy

Primary bindings:

  • LEARN_DB
  • LEARN_PUBLISHED_KV
  • LEARN_UPLOADS_BUCKET
  • LEARN_CERTIFICATES_BUCKET
  • LEARN_ANALYTICS_QUEUE
  • LEARN_WORKFLOW_QUEUE

Reserved future additions:

  • Durable Objects for live room presence and real-time collaboration
  • Workflows bindings for durable multi-step certificate and reminder orchestration
  • Stream bindings for recorded and live session media

Environment Strategy

Each environment resolves:

  • ENVIRONMENT
  • SERVICE_ID
  • TOPOLO_AUTH_API_URL
  • FRONTEND_URL
  • PLATFORM_HOST

The shared service id is srv_topolo_learn. The web runtime consumes the same service id for login config, authenticated home path, app-switcher handoff, and shared transition surfaces.

Auth and Permissions

The browser uses @topolo/auth-client for login, refresh, and callback handling. The worker uses @topolo/auth-middleware to validate requests and then applies TopoloLearn role checks against tenant-local data before returning operator, studio, or member payloads.

@topolo/ui-kit now also supplies:

  • app launcher
  • first-party icon rendering
  • auth/loading transition surfaces
  • bug reporter integration

Data Ownership

Infrastructure configuration, hostname mappings, theme snapshots, learning state, assessment state, enterprise-seat state, and certificate state belong to TopoloLearn. Identity, session, and service-catalog concerns stay in shared Topolo Auth systems.

Public runtime content is currently persisted alongside brand records in brands.site_content_json so the runtime can consume edited copy, faculty, and FAQ blocks without introducing a separate page-builder service yet.

Deployments

The initial deployment shape is one Pages surface for apps/web and one Worker service for apps/api, both represented in PlatformApplications/TopoloLearn/topolo.cloudcontrol.json.

Hostname Resolution

Resolution path:

  1. worker receives hostname
  2. lookup brand_domain
  3. fetch the associated brand and its published runtime data
  4. return the published route-safe payload for the requested surface
  5. web app applies brand CSS variables before rendering public or member navigation

For internal routes on the platform host, the browser still loads runtime brand options from hostname resolution, but it does not use fallback brand identity to title the shell or scope studio API reads. Platform-role studio users must choose an explicit brandId scope before the route outlet mounts.

The current Worker can seed an empty D1 database from the bundled demo catalog for bootstrap environments. If no D1 binding is available, the repository falls back to the seeded in-memory catalog for local development rather than leaving the runtime empty.

Learner submissions now use a dedicated member mutation path. The current v1 shape writes submission rows and submission version rows directly in D1 and records matching audit and analytics events. File-object storage still uses an object-key reference rather than a full R2 upload session handshake.

Public vs Member Runtime Separation

Public and member routes live in one browser codebase but are separated by:

  • hostname-aware runtime context
  • route groups
  • auth requirement
  • navigation model
  • content and data access rules

This avoids duplicating build and theme logic while preserving explicit authorization boundaries.

Caching Strategy

  • brand snapshots are intended for KV-backed fast reads
  • public runtime payloads are cacheable at the edge by brand and route
  • member payloads remain personalized and auth-scoped
  • certificate verification responses can be cached by code once revocation semantics are defined

Observability Strategy

  • audit events capture actor, action, resource, and metadata
  • analytics events capture page, programme, offer, enrolment, submission, review, and certificate milestones
  • queue fan-out is the intended path for downstream analytics sinks

Domain Mapping

Each brand can own:

  • a default platform hostname
  • optional custom public domains
  • optional custom member domains

brand_domains.surface disambiguates which runtime the hostname should boot.

The current studio implementation can create additional public or member hostnames directly through the Worker. Primary-surface selection is modeled by ordered hostname arrays in the brand snapshot and mirrored into brand_domains.is_primary.

Failure Modes

  • stale published snapshots can serve outdated theme or navigation data
  • missing binding configuration blocks persistence or asset delivery
  • bad hostname mappings route traffic to the wrong brand or runtime surface

Debugging

Inspect apps/api/src/routes/runtime.ts, apps/api/src/repositories/store.ts, apps/web/src/components/RuntimeProvider.tsx, the D1 schema, and the CloudControl manifest together when hostname or surface boot behavior is incorrect.

Change Log / Verification

  • Updated the technical architecture on 2026-04-09 to document explicit studio brand selection for platform roles, neutral internal shell behavior, and the super_admin studio-access fix
  • Updated the technical architecture on 2026-04-08 to document the studio/pages content-management route, brands.site_content_json persistence, and the learner-side submission/version write path
  • Updated the technical architecture on 2026-04-08 to reflect the new studio write-paths for brand-token/navigation editing, domain creation, and enterprise account provisioning alongside the earlier route-scoped runtime rebuild
  • Updated the technical architecture on 2026-04-08 to reflect the rebuilt Topolo-native shell, route-scoped Worker API, D1-aware repository loading, bootstrap seeding behavior, and shared bug-reporter/app-launcher integration
  • Added the initial TopoloLearn technical architecture covering workspace layout, shared package usage, bindings, hostname resolution, caching, and observability on 2026-04-08.