Academy OS — Technical Architecture

How the orchestration layer is structured, how the data flows, how each ed-tech platform is integrated, and the 12-week path to a production MVP we'll run at our Boca Lago pilot site. Designed to scale to school districts and, ultimately, to a fully online curriculum.

For the UF Innovate Incubator · technical & mentorship review
⚠
Honest status, May 2026: the demo on the Mac Mini is a frontend mock with a local LLM tutor. Real platform connectors, the event bus, and the curriculum router are designed but not built. The 12-week plan below is the scope we want to build with mentorship and a builder team assembled through the UF ecosystem. We are not pretending the engineering is done.

01 System architecture

Five layers. Each one isolated behind a clean contract so we can swap any component — including the LLM, the queue, the database, or the underlying ed-tech platforms — without touching the others.

Presentation
Browser & email
Guide Monitor React + WebSocket Learner View React on Chromebook Subject Monitor React · roadmap Parent Digest MJML email · Postmark Admin Console React · TanStack
▲
Edge / API
Public surface
REST API FastAPI · Python 3.12 WebSocket gateway /ws/monitor Auth Auth0 + SAML SSO Rate limit / CORS Cloudflare
▲
Application
Business logic
Curriculum Router Alert Engine Mastery Aggregator Incentive Engine Academy Bucks Digest Generator LLM-summarized Roster / Tenancy
▲
Event Bus & Data
Source of truth
Redis Streams event bus Postgres 16 primary store · TimescaleDB ext. S3 raw payload archive ClickHouse analytics · phase 3
▲
Integration
Adapter layer
Math Academy adapter Khan / Khanmigo adapter Membean adapter NoRedInk adapter eGUMPP adapter MobyMax adapter GoGuardian webhook LiveSchool / ClassDojo

02 Core data model

Eight tables get us 80% of the way. The student is one record. Every platform event references that record, so cross-platform analytics is a single JOIN — not an ETL nightmare.

schoolcore
iduuid · pk
nametext
tierenum
tenant_slugtext · unique
created_attimestamptz
studentcore
iduuid · pk
school_iduuid
display_nametext · enc.
grade_levelint
birthdatedate · enc.
guardian_emailcitext · enc.
platform_accountcore
iduuid · pk
student_iduuid
platformenum
external_idtext
access_tokenjsonb · enc.
last_sync_attimestamptz
curriculum_nodecore
iduuid · pk
subjectenum
grade_bandint4range
objective_codetext · CCSS/NGSS
platform_mappingjsonb
prereq_idsuuid[]
mastery_eventevent
student_iduuid
node_iduuid
platformenum
scorenumeric(5,2)
time_on_task_sint
occurred_attimestamptz · idx
behavior_signalevent
student_iduuid
signal_typeenum
sourceenum · GoGuardian, …
severityint 1-5
payloadjsonb
occurred_attimestamptz
alertderived
student_iduuid
levelenum · green/amber/red
reason_codetext
contributing_signalsuuid[]
acknowledged_byuuid · guide
resolved_attimestamptz
daily_pathderived
student_iduuid
datedate
node_sequenceuuid[]
platform_routingjsonb
generated_byenum · rules/ml
router_versiontext
academy_bucks_ledgerevent
student_iduuid
deltaint
reasontext
trigger_event_iduuid
issued_byuuid · guide or system
created_attimestamptz

03 Per-platform integration matrix

Every platform is wrapped in a Python adapter that exposes a uniform interface to the rest of the system. Some platforms are clean — others require SSO + scraping the mastery export. The pattern below is the same in all cases; the implementation differs.

Platform API quality Auth pattern Sync mode What we pull Effort
Math Academycore math · K–12 REST · documented OAuth2 + per-student JWT Webhook + poll fallback mastery_events, time_on_task, lesson_id, struggle_index ~1 wk
Khan / Khanmigoscience · ELA · tutor REST · partial · Khan Districts Khan Districts API key Poll · 5 min video_watch, exercise_score, conversation summaries (Khanmigo) ~2 wk
Membeanvocabulary · 5–12 CSV export + LTI 1.3 LTI deep-link + admin CSV Nightly CSV · LTI handshake on launch session_minutes, words_mastered_tier2, accuracy ~2 wk
NoRedInkwriting · grammar LTI 1.3 + teacher export LTI launch + SSO LTI grade passback + nightly assignment_score, skill_mastery, time ~2 wk
eGUMPPgrammar drills No public API · admin reports only Admin login + reports scrape Nightly scrape · playwright module_complete, score, lesson_time ~3 wk
MobyMaxK–8 catch-up REST · partial · district tier OAuth2 · district admin Poll · 15 min diagnostic_results, lesson_progress, grade_equivalent ~2 wk
GoGuardianbehavior / safety Webhooks · documented OAuth2 + signed webhook Real-time webhook tab_open, idle_threshold, flagged_url, off_task ~1 wk
LiveSchool / ClassDojoincentives REST · documented OAuth2 · school Push on mastery event write-only · award_points ~1 wk

The Adapter contract — one Python interface every platform implements

# integrations/base.py class PlatformAdapter(Protocol): def get_student_state(self, student_id: UUID) -> StudentState: ... def launch_lesson(self, student_id: UUID, node_id: UUID) -> LaunchURL: ... def ingest_event(self, raw: dict) -> NormalizedEvent: ... def sync_mastery(self, school_id: UUID, since: datetime) -> list[MasteryEvent]: ... # Each platform (MathAcademyAdapter, MembeanAdapter, eGUMPPAdapter…) # implements the same 4 methods. The Application layer only knows the interface. # Adding a new platform = writing ONE file, registering it in the platform enum. → This is the single most important architectural decision in the system.

04 Real-time event pipeline

A mastery event or behavior signal travels from any platform to the Guide's screen in under 2 seconds. Here's the exact path.

1

Source

Math Academy emits a mastery event. GoGuardian fires a tab-open webhook. Membean exports overnight.

POST /webhook · 8 sources
2

Ingest

The matching adapter validates the signature, normalizes the payload, archives raw JSON to S3.

FastAPI handler · ~30 ms
3

Bus

Normalized event is appended to a Redis Stream partitioned by school. Consumer groups fan out.

XADD events:{school} *
4

Process

Alert Engine evaluates rules. Mastery Aggregator updates rollups. Incentive Engine awards Bucks if applicable.

3 consumer workers · idempotent
5

Deliver

Guide's Monitor dashboard receives a WebSocket frame. Tile color changes. Optional Slack/email if no ack in 60 s.

WS push · < 100 ms
Platform→ Adapter→ Redis Stream→ Workers→ Guide screen
End-to-end target < 2 seconds P95 from external webhook to Monitor tile update · the entire UX depends on this

05 The Curriculum Router — three phases

The Router is the part most reviewers ask about. It decides what each student does next, on which platform, in what order. We are deliberate about evolving it in three phases — not pretending the V1 is ML when it isn't.

Phase 1 · today

Static rules + JSON config

A YAML curriculum map authored by the Tutoring Director. Maps each (grade, subject, objective) tuple to a preferred platform + lesson. Routing is "next pending objective in priority order, with prereqs satisfied."

Built by week 6 of MVP · zero ML risk · fully auditable
Phase 2 · 2027

Contextual bandit

When an objective has 2+ platform options (e.g. Khanmigo vs. NoRedInk for a writing skill), a Thompson-sampling bandit selects per student based on historical mastery-per-minute on similar objectives. ε-greedy fallback to the YAML preferred.

After ~10k logged daily paths · candidate for a UF research collaboration
Phase 3 · 2028+

Learned policy

Sequence model (transformer on the mastery-event log) predicts which next objective + platform combination maximizes a student's 30-day mastery gain. Trained on cross-cohort data. Always reviewable by Tutoring Director — never autonomous on its own.

Requires ~3 cohorts of data · strongest moat the system has

06 The technology choices & why

Every choice optimizes for two things: a small builder team can ship it, and we can replace any component without rewriting the rest.

Language · backend
Python 3.12
Most ed-tech adapters are easier in Python (lots of CSV / scraping / LLM work). Type hints + Pydantic make it tolerable at scale.
Web framework
FastAPI
Async by default, automatic OpenAPI schema, the WebSocket story is built-in. Good for a small team writing both REST and WS.
Database
Postgres 16 + Timescale
Boring on purpose. Timescale extension handles the high-write mastery-event log without adding a second store. JSONB for raw payloads.
Event bus
Redis Streams
Right-sized. Kafka is overkill at our volume. Streams give us consumer groups, replay, and ordering — without the operational tax.
Frontend
React + Vite + TS
TanStack Query for server state, Tailwind for styling. The Guide Monitor must feel instant — Vite HMR keeps iteration fast.
Real-time
Native WebSockets
One persistent /ws/monitor connection per Guide session. Redis pub/sub fans out from the Application layer. No third-party RT vendor lock-in.
Auth · school
Auth0 + SAML
Districts require SSO via Clever, ClassLink, or raw SAML. Auth0 covers all three without us re-implementing it. SCIM for roster sync.
Hosting
Fly.io → AWS
Fly.io for the MVP (1 region, $200/mo). AWS once we cross 5 districts — VPC isolation per tenant becomes a procurement requirement.
LLM
Claude · Sonnet 4.6
Parent digest summaries, Khanmigo conversation classification, optional in-product tutor. Cheap, fast, and the safety profile fits ed.
Observability
Sentry + Datadog
Sentry for errors, Datadog for the WebSocket and Redis Stream lag we need to watch. Both have free or startup tiers we qualify for.
CI / deploy
GitHub Actions
Workflow per environment, dependabot, OIDC to cloud. Boring on purpose.
Local demo
Ollama + Open WebUI
Already running on the Mac Mini. Demonstrates the tutor surface offline, with zero cloud dependency, for incubator visits.

07 Frontend surfaces

Four surfaces, one backend. Each surface is scoped to a specific user and a specific moment in the day.

Live · demoed

Guide Monitor

For Guides · whole-day owner view
20 student tiles, real-time status (green / amber / red), platform-by-platform progress bars, alert queue on the right rail. Built so an adult can stand in a room of 20 kids and instantly see which two need them.
Update rate: WebSocket pushes, < 100 ms render
Refresh model: long-lived /ws/monitor connection per session
Devices: Mac, Windows, Chromebook · 13"+ screen
Live · demoed

Learner View

For students · daily path
Today's lessons in order. Each tile launches the right platform with the right lesson preloaded via the adapter's launch_lesson() method. Academy Bucks counter, reflection prompt at end of block.
Device: Chromebook or iPad
Launch latency target: < 800 ms to platform load
Offline mode: caches today's path; sync on reconnect
Roadmap · Q2 2027

Subject Monitor

For subject teachers · period-scoped
Same backend, different filter. A 3rd-period AP Bio teacher sees only their cohort, only Khanmigo + AP Classroom, only this period. Critical for public middle/high deployment.
Differs from Guide Monitor: tenancy filter by (teacher, period, cohort)
Backend: 0 new tables — view-layer only
Unblocks: the full public-school market
Live · template

Parent Digest

For parents · weekly summary
Server-rendered email. Mastery gains per subject, time on task, Academy Bucks earned, what's next. LLM-summarized into 4 sentences so it actually gets read.
Format: MJML → Postmark
Send time: 4 PM daily + Friday weekly
Personalized by: grade, recent mastery, language preference

08 Security, privacy & compliance

No district will sign a pilot without these answers. We design for them from day one — not retrofitted before the first big contract.

FERPA Federal · student records

  • Academy OS acts as a "school official" under §99.31(a)(1)(i)(B) — contractual, performing a function the school would otherwise do itself
  • Data Processing Agreement signed per district before any production data flows
  • PII (name, DOB, guardian email) encrypted at rest via pgcrypto field-level encryption
  • Audit log of every read of a student record · 7-year retention

COPPA Federal · under 13

  • Parental consent collected at enrollment, stored as a signed artifact in S3
  • No third-party advertising trackers · period
  • Data minimization — we collect mastery events, not keystroke logs or biometrics
  • Parent can request data export or deletion via the Parent Digest portal

Florida-specific FL HB 1547 / SB 7000

  • FL Student Online Personal Information Protection Act compliance
  • Voucher-funded student data follows the same protections as district-funded
  • Data residency: us-east-1 (Florida proximate, US sovereign)

Sub-processor governance Third-party vendors

  • Every ed-tech vendor we orchestrate has its own DPA on file
  • We do not pass student data between vendors we orchestrate — each adapter is one-way pull
  • OAuth tokens stored in AWS KMS, never in application code

App security Standard hygiene

  • SSO-only login for adults · MFA enforced
  • SCIM 2.0 roster provisioning from district IDPs (Clever / ClassLink)
  • Row-level security in Postgres per tenant — defense in depth
  • SOC 2 Type I targeted Y2 once we cross 3 district contracts

Incident response When something goes wrong

  • 72-hour breach notification window per FERPA / district DPA
  • Synthetic monitoring of every adapter — alert if mastery feed goes silent > 30 min
  • Runbook owned by Lucca for V1 · designated incident commander rotation post-Y1

09 The 12-week MVP build plan

This is the scope we want to build with a UF-supported builder team. Boca Lago is the design partner and pilot site. The mock dashboards we demo today become real, end-to-end, by week 12.

Weeks 1–2 · foundation

Project setup, data model, auth

Postgres schema migrated, Auth0 tenant configured, basic Roster API live, CI deploying to Fly.io. Deliverable: a logged-in Guide can see an empty Monitor.

Lucca + 1 UF
Weeks 3–4 · first adapter end-to-end

Math Academy adapter, ingest, persistence

Webhook signed and verified, normalized into mastery_event, archived to S3. Deliverable: a real student lesson on Math Academy lands as a row in our database within 2 seconds.

Lucca + 2 UF
Weeks 5–6 · event bus & alert engine

Redis Streams, alert rules, WebSocket

Mastery events fan out through Redis. The Alert Engine runs the first 6 rules (idle, off-task, mastery dip, streak break, ChatGPT-tab, prereq-block). Deliverable: tile colors change in real time on the Monitor.

2 UF
Weeks 7–8 · second & third adapter

GoGuardian webhook + Khan / Khanmigo polling

Behavior signals flow alongside mastery events. The Alert Engine correlates them. Deliverable: "Jordan opened ChatGPT" + "Jordan stalled on lesson" combine into one red flag, not two.

2 UF
Weeks 9–10 · curriculum router V1 + Learner View

YAML config, daily path generator, Chromebook UX

The Tutoring Director's YAML compiles into a per-student daily_path. Learner View on a Chromebook launches lessons via launch_lesson(). Deliverable: a student can complete a full block driven entirely by Academy OS.

Lucca + 2 UF
Weeks 11–12 · parent digest, hardening, pilot launch

Email digest, observability, security review

MJML email pipeline live, Sentry + Datadog wired, penetration test against the Monitor, FERPA DPA signed with the academy. Deliverable: 20 real students start day 1 of the Boca pilot on the live system.

Lucca + 1 UF

10 Scale targets & honest economics

The architecture scales because the heavy lifting (mastery instruction) happens on the platforms we orchestrate — not on our servers. We're moving small, structured events. The math is generous.

10k
Concurrent students
target by end of Y2 · ~50 schools at 200 avg
~200/s
Peak events/sec
20 events per student per active hour · Redis Streams handles ~10× this on a single node
< 2 s
P95 webhook → screen
the entire UX depends on this · Datadog monitor blocks deploys above 3 s
$0.18
Infra cost / student / month
at 10k students on AWS, including LLM costs · < 1% of license revenue

11 What we want from UF specifically

We are not raising capital right now. We're seeking mentorship, help assembling a builder team, and partners who think about scale and online curriculum the way we do. Our pilot site is already committed — Boca Lago, run by our own family team.

Mentorship

  • Operator and ed-tech mentors inside the Incubator network — people who've taken a learning platform from one site to district-scale rollout
  • Architectural review on the orchestration layer, the event pipeline, and the curriculum router as it evolves through its three phases
  • Honest feedback on what we're getting wrong before the pilot, not after

Help assembling a builder team

  • The 12-week plan above is the scope we want to ship — we need engineers to build it alongside us
  • UF CS students, recent grads, or referrals from the Incubator network — the goal is a small, opinionated team, not a contracting shop
  • Real product work, real students using it, real portfolio pieces for the builders

Pilot site · already committed

  • We're trialing at our Boca Lago property in Florida — controlled environment, Aguiar family team running ops
  • UF's role: shape the assessment so the results travel beyond one site
  • An education-research faculty advisor would meaningfully strengthen the Y1 white paper

Scalability & online curriculum

  • Strategic guidance on the path from one pilot to school-district deployment — procurement, FERPA-at-scale, multi-tenancy hardening
  • Thinking partners on extending Academy OS into a fully online curriculum offering, beyond brick-and-mortar sites
  • This is where the company-scale opportunity lives — and where UF's network is most valuable to us
Academy OS · Aguiar Family · prepared for the UF incubator · May 2026