TopoloLearn Setup And Operations

What It Is

This page is the setup and operations guide for TopoloLearn. It covers local development, bindings, auth integration, tenant and brand setup flow, seeding, deployment, and current scaffold limitations.

Architecture

Operationally, TopoloLearn consists of a browser app, a Worker API, shared Topolo Auth dependencies, and Cloudflare resources for relational data, object storage, caching, and async work.

Runtime Surfaces

• local web runtime via apps/web
• local API runtime via apps/api
• CloudControl manifest and Cloudflare resource bindings

API Reference

Operational checks should center on the runtime-resolution, overview, assessment-review, certificate-issuance, and verification routes because those are the current end-to-end surfaces exercised by the scaffold.

Local Development

Expected entrypoints:

• pnpm install
• pnpm dev
• pnpm typecheck

The initial workspace exposes apps/web and apps/api as the main local entrypoints.

Bindings And Environment

The declared runtime bindings are:

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

Core vars:

• ENVIRONMENT
• SERVICE_ID
• TOPOLO_AUTH_API_URL
• FRONTEND_URL
• PLATFORM_HOST

Auth Integration

TopoloLearn depends on:

• Topolo Auth service registration for srv_topolo_learn
• shared login config
• shared landing config
• shared app UI config
• shared onboarding config
• the shared first-party app registry entry in @topolo/ui-kit

Auth and Permissions

Topolo Auth registration for srv_topolo_learn is required before login, app-switcher visibility, and shared routing metadata behave correctly. Tenant-local role data inside TopoloLearn still controls which authenticated users can operate, administer, assess, or learn.

Data Ownership

Operationally, TopoloLearn owns its D1 schema, R2-managed uploads and certificate assets, published brand data, and product-local analytics and audit records. Shared identity and service-catalog state are operated in Topolo Auth.

Deployments

TopoloLearn deploys from PlatformApplications/TopoloLearn/topolo.cloudcontrol.json as a Pages web surface plus a Worker API surface backed by D1, KV, R2, and queue resources.

Tenant And Brand Creation

The intended initial flow is:

1. create tenant
2. create first brand
3. attach default platform hostnames
4. configure theme tokens
5. seed programmes, cohorts, artefact requirements, and certificate template
6. invite team roles and learners

Domain Setup

brand_domains is the canonical mapping table. Public and member domains are separate rows distinguished by the surface column.

Seeding

The first working pass ships with typed demo data for:

• a demo tenant
• The B2B Faculty tenant
• a flagship brand
• a ten-week programme
• artefact and evidence-pack workflows
• a certificate template and one issued certificate

Deployment

CloudControl manifest:

• PlatformApplications/TopoloLearn/topolo.cloudcontrol.json

Declared deploy surfaces:

• Pages project for apps/web
• Worker for apps/api

Known Limitations

• Stream, Durable Objects, and Workflows are documented but not fully implemented in the first scaffold
• the first seed path is optimized for local demo coverage rather than complete operator automation
• the Cloudflare binding ids in wrangler.toml are placeholders until real resources are provisioned

Failure Modes

• missing Cloudflare resource ids prevent the scaffold from moving past local placeholder mode
• missing Topolo Auth service registration blocks login and app-switcher integration
• stale or absent seed data prevents the demo flows from exercising assessment and certificate paths

Debugging

Verify topolo.cloudcontrol.json, both wrangler.toml files, the Topolo Auth SQL registration scripts, and the seed/demo repository layer together when setup or deployment behavior diverges from the docs.

Change Log / Verification

• Added the initial TopoloLearn setup and operations guide on 2026-04-08.