MaestroMaestro Overview — contents
The Build
Architecture & the Trust Layer
How Maestro is built: one modular backend with clear module boundaries, Postgres as the single source of truth, Temporal for long-running authoring work, and one AI gateway for every model call. The learning logic (the trust layer) is deterministic code that no model and no admin setting can change.
Keep the model layer separate from the learning logic. Models are chosen in Admin Center from the gateway's live catalogue and prompts come from a registry of approved versions, so either can change without code. The trust layer (the learner model, the misconception registry and the routing rules) is pure, versioned code with its own append-only records. The mastery engine lives in the platform; the mastery bar is set in the course and frozen at release. There are no runtime dials.
The platform at a glance
| Part | How it is built |
|---|---|
| Backend | A modular monolith: one Node.js service made of domain modules (authoring, Lead Designer, publishing, Journey, trust, milestones, companion, Pulse, LTI and others). Each module owns its data, services, workflows and routes, and exposes a public API through one entry file. Other modules may import only that API, and the boundaries are checked automatically on every build. |
| Front ends | Two web apps, Studio and Journey, sharing typed contracts with the backend. Every request and response is validated against the same schema on both sides. |
| Data | PostgreSQL is the source of truth, with pgvector for embeddings and search over course sources. Tables are grouped into schemas per domain, and the schema changes only through numbered, forward-only migrations. |
| Long-running work | Temporal runs authoring work that takes minutes or hours and must survive restarts: source ingestion, Course Design reviews, and Lead Designer planning, division of sources, gap filling, lesson design, production and video rendering. |
| Events | A durable domain-event table in Postgres. Publishers write the event in the same transaction as the change; subscribers receive it reliably and at least once. |
| Hosting | A containerised deployment on AWS. |
The AI gateway and Admin Center
Every model call, whether text, embeddings, video or voice, goes through one AI gateway. No module talks to a model provider directly.
- No hard-coded models. The model catalogue is the gateway's live list of approved models and their capabilities. IT chooses each model in Admin Center, per job, from that list; a choice is checked against the live catalogue, and a job with no model chosen refuses to run rather than guessing.
- Prompt registry. Every prompt is a registry entry with immutable versions. Editing a prompt adds a new version; only an approved version can be active. Evidence records note which prompt version judged them.
- Every call is audited: the purpose, model, status, timing and size of each gateway call are recorded and summarised for Admin Center.
Realtime voice
The milestone's spoken defense runs as a live voice call over WebRTC through the gateway. The server sets up the session and issues the browser a one-call credential; the browser talks to the voice model directly, and the server joins the same call on a side channel to drive it. The gateway key never reaches the browser. Code decides every question; the model only speaks it. The learner can cut in and the examiner stops. The transcript is stored; the audio is not kept. Atlas's voice mode uses the same gateway's realtime models.
The trust layer
The trust layer is the learning logic that must stay consistent, explainable and independent of any model vendor:
- The learner model: a belief per concept per learner (see Learning Signals).
- The misconception registry: the shared catalogue of tempting errors, each bound to the lesson checks that can detect it.
- The routing rules: which options follow each result (see Adaptivity & Routing).
The engine is a separate package with no I/O: given the same belief and the same evidence it always returns the same result. The AI may rate a learner's reasoning; deterministic rules choose the band, update the belief, run the misconception episode and decide the options. Every belief, ledger event and routing decision is stamped with the engine version, and beliefs change only by appending to a ledger, so any decision can be replayed and explained.
Who owns the mastery logic
| Layer | Who owns it & how it's set |
|---|---|
| The mastery engine | Lives inside the platform. How evidence is read, how beliefs update, how misconceptions are handled and how re-checks are spaced behave the same across every course. |
| The mastery bar | Set in the course. Each check's answer design and band mapping, the misconceptions bound to it, the remediation pieces and the milestones with their weights are authored and approved in Studio, then frozen at release. |
In short: the platform owns the mechanics, the course owns the standard.
No runtime dials
A course reaches learners only when the Dean (or IT Admin) releases a signed version, and a released version is frozen. To change how a course judges mastery, faculty make a new version in Studio and release it; there is no direct publish and no live knob. Rollback is only to an earlier released version.
Records and audit
Learner records are written to be kept, not overwritten. Evidence records and belief events are append-only; a retry is a new record. Each enrolment is tied to a specific released version, lessons are identified by stable ids so records still line up when a later version is released, and a learner's rubric and milestone materials are read from the version they took. High-value staff actions (user and access changes, academic approvals, configuration changes) go to an append-only audit log that Admin Center can filter, and that log is kept even when a course is deleted. Every AI call is logged as above.
LTI and the LMS
Maestro is an LTI 1.3 tool. Instructors deep-link whole courses from the LMS; each approved milestone gets its own gradebook column with its weight; grades return through the assignment and grade service; rosters sync; and learners sign in once and arrive on Your day. Only summarised grades leave Maestro. The detail is in Integration — Moodle & LTI.