Case study · Research

EduBridge Analytica: a research instrument educators can run

Research software for educational data mining. AI suggests spreadsheet mappings and fixed mathematics ranks features as well as educators make the decisions.

Role

Co-author with Henry Chukwudi John: apparatus, protocol, engineering

Timeline

Protocol/SRS freeze 5 Jul 2026 · software v1.0.0 on 10 Jul 2026

Stack

FastAPI · React 18 · PostgreSQL · deterministic Python engine

Output

MIT research apparatus · live demo · published pilot paper

EduBridge Analytica v2 is a research instrument, not a generic "AI for education" demo. It supports a preregistered human-participants study of whether guided feature selection helps educators without replacing their judgement. The live system is available to test.

∑

Source of the numbers. Engineering counts come from repository commit 4c90d2e9 (11 July 2026) or CI thresholds documented in the README. The change from 342 s to 45 s comes from the 2026 peer-reviewed pilot. The full v2 study has not run. Ledger: backups/edubridge-analytica-numbers-ledger.2026-07-15.md.

Try the live Path B demo

Open the stack at edubridge.ahmdmshazly.me (UI on Vercel, API on api.ahmdmshazly.me with TLS). It uses synthetic data and is not an IRB study instance. Do not upload real student data.

⇢

Researcher login (password + TOTP). Username demo-researcher · password ShowcaseTry2026! · TOTP secret HHKS6C3ZC4PFOVMFSYHV37D6CNJRRM42. Add the secret to an authenticator app and enter its six-digit code at sign-in. Then open /console and create a participant session link for the educator path. Each link works once.

Demo security configuration, verified 15 July 2026: EDUBRIDGE_ENV=production, a researcher cookie secret, HTTPS on the API host and a CORS allow-list limited to the UI origin as well as a login that returns a Secure session cookie. Do not reuse these demo credentials on a study deployment.

EduBridge Analytica landing page on the live demo host. — Fig. 01: The live landing page at edubridge.ahmdmshazly.me (captured 15 July 2026).

Why build the apparatus before recruiting

A 2026 pilot with Henry Chukwudi John, published in the Babcock University Journal of Education, found that educators completed guided feature selection in 45 s on average instead of 342 s. Assisted selections overlapped their manual selections by 85-90%. The article about the pilot and the open-access paper (DOI 10.5281/zenodo.20712838) explain the study and its limits.

The pilot had order confounding, two participants and opaque ranking as well as no ground-truth utility criterion. v2 addresses those limits with a counterbalanced protocol, deterministic ranking and append-only telemetry as well as a dry-run harness that checks every study metric before a human session. Epics E1-E9 are complete and the software is released as v1.0.0. IRB approval, consent, and the owner checklist still gate the first participant.

The code is done; the study is not.

What it does, in plain language

An educator uploads course data. The system suggests how each spreadsheet column maps to a shared education vocabulary, but a person must accept, edit, or reject every suggestion. For a research question, fixed mathematics ranks the columns; the same data and task produce the same result. In the "Assisted" condition, the ranking appears beside the manual workspace.

Screens in action (synthetic demo data)

The figures below were captured from the local demo build (VITE_DEMO_MODE=true): a service worker answers every API call from fixtures modelled on the real seed. Nothing is recorded. They cover the educator path, the study instruments and the analytic dashboards as well as the researcher console.

EduBridge start page with links to an explanation, teacher walkthrough, and researcher console. — Fig. 02: The start page links to the explanation, teacher walkthrough, and researcher console.

Demo catalogue listing schema mapping, task runner, dashboards, console, study config, and LLM audit log. — Fig. 03: The demo catalogue links to every available screen.

Schema mapping table with ontology suggestions, confidence bands, and Accept/Edit/Reject decisions. — Fig. 04: Schema mapping (S1) requires one decision per column: Accept, Edit, or Reject.

Feature-selection workspace with research question, candidate columns, inspector, and selection tray. — Fig. 05: Manual feature selection (S3), with profiles available before confirmation.

Assisted feature-selection workspace with the recommendation rail loading beside the same Manual layout. — Fig. 06: The Assisted condition adds an engine-ranked recommendation rail to the Manual workspace. It does not use an LLM.

NASA-TLX post-block workload survey with six required scales. — Fig. 07: NASA-TLX records six workload scales after each block.

Dashboards catalog with student and course analytic questions and a score-distribution chart. — Fig. 08: Dashboards (S4) show charts over mapped data.

Researcher console study configurations with a frozen Kigali pilot cohort. — Fig. 09: The researcher console (S5) manages study configurations and participant links.

Frozen study configuration detail showing task sets A and B with research questions. — Fig. 10: Task sets and conditions freeze when the first participant begins.

LLM audit log table of schema-mapping suggester calls with model, latency, and token counts. — Fig. 11: The audit log records every LLM schema-mapping call. Ranking does not use an LLM.

Five surfaces, one instrument

The monorepo contains a React web app for educators and researchers, a FastAPI service for orchestration and telemetry, a pure-Python engine that never calls an LLM and a versioned education ontology as well as an eval CLI that reproduces statistics from exports. Docker Compose and Caddy provide the production path. The public demo splits UI and API across origins with an explicit CORS allow-list.

Two paths that must not mix

PATH 01 · MAP

LLM proposes columns; humans decide

Schema mapping is the only place an LLM is allowed (ADR-005). A person must verify every suggestion. The LLM cannot write silently or rank features.

PATH 02 · RANK

Deterministic feature recommendations

The engine combines mutual-information relevance and a redundancy penalty as well as permutation importance. The same inputs produce the same canonical ranking. This package does not use an LLM.

PATH 03 · PARITY

Assisted = Manual + one rail

The Assisted condition adds only a recommendation rail. A DOM-diff test prevents "support" from changing the rest of the workspace.

PATH 04 · RECORD

Append-only telemetry + dry-run gate

Study events are append-only at the database role layer. A scripted virtual participant must prove every protocol metric is computable before humans are invited.

Checks and measurements

Python tests · engine, API, ontology, eval

web Vitest cases · including axe states

engine coverage · gate is 90

CI jobs · determinism, load, ZAP, a11y

Fourteen GitHub Actions jobs check Python and web coverage (engine/ontology at least 90%, API/eval at least 80%, web at least 70%), OpenAPI and client drift, cross-OS determinism, dry runs, engine performance, Compose startup, five concurrent k6 sessions, OWASP ZAP (zero High findings) and dependencies as well as axe-core WCAG 2.1 AA across participant and researcher screens. The smoke file currently covers 21 axe states.

What this page will not claim

v2 has not yet run its full human study. Consent stays disabled until IRB clears; the owner checklist still lists freeze tags and Zenodo archival for the study release. A manual screen-reader pass is still recommended before real participants. The demo login uses synthetic data only.

The pilot's 7.6× speed-up is evidence from two educators, not a general effect size. The article and paper provide the full limitations; this page documents the instrument for the next study.

✓

Check the work. Use the demo credentials above, read the pilot article, open the paper, or browse the repository. Treat the live application as current if this page falls behind.

Henry Chukwudi John and I built this citeable, MIT-licensed research apparatus so others can run and audit it. I also engineered The Living Archive, Henry's public scholarly portfolio and CMS.

Next project

ahmdmshazly.me: this portfolio and its content studio

View→