A production system,
built and run in the open.

How the system is built, stage by stage

1. 01

   Problem

   Teaching across several programmes produced the same load weekly: records scattered across documents, progress tracked by hand, nowhere a term’s evidence could be reviewed as a whole.

2. 02

   System architecture

   A server-rendered application on managed cloud hosting over a relational database, deployed continuously from source control, reachable only behind authentication. Vendor-neutral by construction: the data model is the asset, not the provider.

   Application

   Next.js 16 · React · TypeScript

   Data

   PostgreSQL via Prisma · Zod-validated boundaries

   Runtime dependencies

   12, deliberately

   Access

   Authenticated; no public surface

3. 03

   What was built

   A ten-table domain model covering the whole teaching operation rather than one feature, with a command centre for weekly planning on top.

   • Students · Instructors · Lessons · Materials
   • Assessments · Payments
   • Source documents · Review queue
   • Integration health · Scheduled run history
4. 04

   Data integration and AI readiness

   Two scheduled jobs run daily: calendar events are reconciled into lessons, and teaching records are mirrored into Notion. A separate local source-file pipeline tracks files by content hash, so changes, duplicates and disappearances are detected rather than assumed.

   The system does not call a language model, deliberately. Source-document tracking and a human review queue are precisely the grounding and oversight substrate a retrieval-grounded assistant requires. The data discipline comes first; the model is added afterwards, if evidence justifies it.

5. 05

   Operational use

   It runs unattended on a schedule, as working infrastructure rather than a demonstration. The scheduler guarantees only hourly precision and does not retry a failed invocation, so the design accepts both: the two jobs have start windows an hour apart (not a completion dependency), every run is recorded durably, and a missed run is surfaced rather than assumed. Scheduled requests are authenticated and fail closed if the secret is absent. Failures in credential expiry, host permissions and third-party API changes were diagnosed and fixed in production — the part that never appears in a prototype.

6. 06

   Evidence

   Diagrams generated from the system’s own schema and scheduling configuration.
   No student, staff or institutional data appears in any of them.

   Architecture in practice
   01 / Architecture

   Two planes,
   one system.

   Teaching is what happens.
   Operations hold the evidence.

   Teaching core

   StudentLearner

   InstructorEducator

   LessonLearning experience

   AssessmentProgress

   MaterialResources

   PaymentStudent billing

   Operations plane

   SourceDocument Source filesReviewItem Review queueIntegrationHealth Connector healthCronRun Run history

   View architecture evidence

   Six teaching models, four operations models. Lesson belongs to a Student and Instructor; Material is optional. Assessment belongs to Student and can reference Lesson. Payment belongs to Student, not Lesson.

   ReviewItem can reference SourceDocument. IntegrationHealth and CronRun are independent tables. The two planes are conceptual groupings, not a database relationship.

   02 / Automation

   Two daily jobs.
   A deliberate sequence.

   Bring the calendar in.
   Then mirror teaching records out.

   11:00 UTCCalendar → Lessons

   1. Calendar
   2. Reconcile
   3. Lessons

   ‹‹1 hour separation››

   12:00 UTCTeaching records → Notion

   1. Database
   2. Synchronise
   3. Notion

   Each authorised job invocation
   starts a CronRun record.

   View scheduling evidence

   0 11 * * * → /api/cron/daily-sync
0 12 * * * → /api/cron/notion-sync

   Start windows are one hour apart; completion order is not locked. The noon job mirrors Students, Instructors, Lessons, Payments and Assessments into Notion.

   Source-file hashing and review are a separate local pipeline, not the noon cloud job. Requests require the cron secret; unauthorised requests are rejected before creating a run.

   03 / Observability

   Nothing fails
   silently.

   See what ran, what worked,
   and what needs attention.

   1. RunWork begins
   2. RecordedHistory saved
   3. Health updatedConnector state
   4. Failure surfacedAction is visible

   Run historyJob · timing · outcome · errorCronRun

   Connector healthHealth · last sync · last error

   A reachable connector does not prove a scheduled job succeeded. Both signals matter.

   View observability evidence

   CronRun
   job · startedAt · finishedAt · ok · error · trigger

   IntegrationHealth
   healthy · lastSyncAt · lastError

   Derived status, not stored health fields: ok, failed, missed, blocked, none. “Missed” means the last successful run is stale; it is not a measured count. Connector health is persisted by the Notion integration separately from run completion.

   This illustrates the recording design, not a live monitor or a guarantee against every infrastructure failure. No sample records or invented metrics are shown.

   Source-derived architecture. No live records.Understand the system. Inspect the evidence.

7. 07

   Transferability

   The pattern moves to institutional work unchanged: a defined data model, a scheduled reconciliation pipeline, grounded assistance under human review, and observability that survives real failure. What changes for a university is governance, scale and where review sits — not the architecture.