For engineering

Asset Platform — Architecture

How content assets are discovered, described, embedded, verified and linked to journeys — and how that runs distributed across many machines writing into one shared store.

Two systems, joined by a tag

The platform keeps two concerns deliberately separate, connected only by the asset ↔ journey tag:

1 · Asset catalog (system of record)

Curriculum-agnostic. Every asset that exists — video, image, interactive, document — with its provenance, media location and a machine-written brief of what it teaches. This is what the portal shows.

2 · Knowledge graph (LOs & journeys)

The learning structure the chapter-research side produces. The catalog never owns journeys; it only carries a tag from an asset (or asset part) to the journey / LO it covers.

Keeping them apart means the same asset can be reused across journeys, and the graph can evolve without rewriting the catalog.

The pipeline

each unit: Extract → Describe → Embed → Match → Verify → Link (bold = an LLM pass)

Extract — pull the raw signal: transcript for video (Whisper), vision/text for images and documents.
Describe — an LLM turns the raw extract into a structured brief: pedagogical intent, content moments, characteristics.
Embed — the brief (and asset parts) are embedded into a vector so they can be searched by meaning.
Match — candidate journeys/LOs are retrieved by vector similarity.
Verify — an LLM confirms each candidate link with evidence, rejecting weak matches.
Link — the confirmed tag is written: asset → journey. Only now is the unit “done”.

Assets and parts

A file used in slices — a book read a page at a time, a video referenced by timestamp — is an :Asset with :AssetPart children (PART_OF). The part is what gets tagged and embedded, so a single source can serve many journeys at different locators.

Distributed by design (no LAN)

Discovery happens on many machines, none on a shared network. Every seat is an outbound-only HTTPS client of one central hub:

Browser / worker ──HTTPS──▶ Cloudflare Pages ├─ index.html (static portal) └─ functions/ax/[[path]] ─HTTPS(secret)─▶ mcp-db ─▶ Postgres

Atomic claims — a worker claims a unit with UPDATE … FOR UPDATE SKIP LOCKED, so two workers never collide.
Leases — a claim expires; a stalled unit becomes reclaimable, never lost.
Idempotent writes — enqueue and submit are keyed by content_key, so re-runs never duplicate.
Roles — a populator token enqueues (content team, via the MCP); worker tokens claim and extract. Read (/ax/status) is open behind the login.

Data model

Table	Holds
ax_asset	one row per content-addressed asset — provenance, product, curriculum, grade, kind, title, chapter, media location, servable
ax_work	the work queue & claim lock — stage (pool→claimed→…→done), claimed_by, claim_expires, attempts
ax_brief	the Describe output — the structured brief JSON, a hash, and a pointer to the raw extract
ax_token	who may do what — worker / populator / admin bearer tokens

Embedding, vector index and the journey tag land in a later migration (bge-m3 embeddings, a Neo4j graph with vector indexes). Briefs come first.

Hosting

Cloudflare Pages — the portal (static) and the hub (Pages Functions under /ax/*), one origin, behind Cloudflare Access (ClassRoots login).
Postgres via the mcp-db gateway — the hub reaches the DB over HTTPS with a server-side secret; no open DB port, no driver in the edge runtime.
Hardening path — swap the gateway for Hyperdrive + parameterized pg; move embeddings to a self-hosted bge-m3 as the pool grows.