Case Study: EdTech Mastery Engine

Redacted architecture case study. School names, teacher names, student data, domains, and private source code are withheld. This public repo documents the architecture and engineering decisions.

One-line summary

A production-shaped EdTech SaaS for English teaching: teachers mark work and assign learning targets; the system generates personalised micro-tasks; students complete them; teachers and parents see mastery progress update over time.

Why this is technically interesting

The pilot scope was intentionally small, but the product was engineered as if it had to survive real school usage: role-based portals, audit logs, tenant modelling, seedable curriculum content, connection pooling, CI, security scanning, backups, runbooks, and load-test artefacts.

Scale / build facts

• 858 commits over six months.
• TypeScript monorepo.
• Express backend, Prisma/Postgres, React/Vite frontend.
• 26 REST endpoints.
• 11 core tables around schools, users, students, classes, targets, tasks, task responses, parent links, and audit logs.
• 60+ curriculum targets and 600+ multiple-choice task templates.
• CI for security checks, backend tests, linting, typechecking, and real Postgres integration tests.

System architecture

┌─────────────────────────────┐
│ Teacher portal               │
│ - class dashboard            │
│ - mark work                  │
│ - select learning targets    │
│ - monitor mastery            │
└──────────────┬──────────────┘
               │
┌──────────────▼──────────────┐
│ Express API                  │
│ - auth + refresh tokens      │
│ - RBAC middleware            │
│ - task generation services   │
│ - audit logging              │
│ - clean architecture layers  │
└──────┬──────────────┬───────┘
       │              │
┌──────▼─────┐ ┌──────▼──────┐
│ Student UI │ │ Parent UI    │
│ - tasks    │ │ - progress   │
│ - feedback │ │ - timeline   │
└──────┬─────┘ └──────┬──────┘
       │              │
┌──────▼──────────────▼──────┐
│ Postgres + PgBouncer        │
│ - schools / users / classes │
│ - targets / tasks / answers │
│ - audit logs                │
└─────────────────────────────┘

Main engineering decisions

1. Three-portal model

Teacher, student, and parent users have different information needs and permissions. The architecture treats them as separate product surfaces rather than one dashboard with conditional rendering everywhere.

2. Clean backend layering

The backend separates presentation, application, domain, and infrastructure layers. That keeps controller code thin and makes the target/task-generation logic testable without HTTP concerns.

3. Curriculum as seedable product data

Learning targets and task templates are not hard-coded UI copy. They are seeded domain data. That makes pilots repeatable and lets the product evolve from one school to many without rewriting flows.

4. Audit logs as first-class data

Education data has trust and safeguarding implications. Mutations are logged with actor and tenant context, not treated as an afterthought.

5. Production posture before scale

PgBouncer, structured logging, graceful shutdown, security scanning, runbooks, and load-test notes were added before the pilot reached scale. That is deliberate: school pilots fail fast if reliability looks amateur.

What a developer should notice

• The repo is not just a UI prototype; it has operational shape.
• The domain model anticipates multi-school scale even though the pilot started with one school.
• Curriculum content is represented as data, not copy pasted into components.
• The system includes parent visibility and auditability from the start.

What I would improve next

• Convert task-generation rules into a more explicit rules engine.
• Add richer mastery analytics over time.
• Add import/export flows for school MIS systems.
• Tighten frontend parity with the already mature backend.