Super Teacher

A teacher workspace for finding students who need attention and acting on grades, attendance and classroom notes. Built with React, TypeScript and FastAPI.

Status: active; a Cloud Run pilot is the accepted deployment shape. The public domain may still serve the older edutrack app, so source capabilities are not deployment evidence. Read the release checkpoint and deployment status before making release decisions.

What it does

• Today and roster: class summaries, risk reasons, search, filters and CSV import.
• Student and gradebook: assignment scores, grade history, notes and spreadsheet-style score entry.
• Attendance and reports: daily roll call, assignment statistics, CSV export and editable parent-update drafts.
• Ask AI: streamed chat with scoped classroom tools and student insights. Rule-based insights and template parent drafts work without an API key; chat reports that AI is unavailable.
• Authentication: shared passcode by default; optional email-link accounts with owner-scoped data, revocable sessions, quotas, export and deletion.

Quickstart

For a synthetic local demo on Linux/WSL, install uv, Node 22.22.2+ and GNU Make, then run:

make dev-check            # tools/ports only; no installation or servers
make dev                  # first run installs; later runs reuse matching locks

This starts the API on loopback port 8080 and Vite on loopback port 4000 with synthetic seeded data, disabled auth and no AI or email credentials; open http://localhost:4000. ./local_test.sh is an alias.

For other platforms, an existing environment, an empty classroom, or testing login and AI, follow the manual setup (Python 3.11+, Node 22.22.2+). The managed demo's safety checks and settings are in the same local development guide. ANTHROPIC_API_KEY is optional; keep credentials outside Git.

Architecture

flowchart LR
  UI[React workspace] -->|REST and WebSocket| API[FastAPI routers]
  API --> Data[Queries and metrics]
  Data --> DB[(SQLAlchemy database)]
  API --> AI[Optional AI services]
  AI --> Data

Loading

Layout

Path	Contents
web/	React + TypeScript app (Vite)
superteacher/	FastAPI application, routers, models and AI services
alembic/	Database migrations
tests/	Python test suite
e2e/	Playwright browser and accessibility suite
scripts/	Dev launcher, benchmarks, deployment and lock tooling
infra/	Terraform for the Cloud SQL plan
docs/	Architecture, operations, release and planning documents

Documentation

• Architecture and data boundaries and architecture decisions
• Teacher flows, frontend and authentication
• Local development
• Configuration and deployment: accounts, email and runtime settings
• Operator runbook: deployment, rollback, recovery, credential rotation and incident triage
• Backup and recovery and release checklist
• Security review and roadmap
• Browser suite findings and dependency locking
• Full documentation index
• AGENTS.md and agent architecture notes for coding agents

Development

CI runs Python lint/tests, web lint/types/tests/build, browser/E2E tests, Docker/auth smoke and a benchmark. Run relevant checks after changes; in shared agent workspaces, use the repository's verification owner and resource gate for broad suites, builds and installs.

ruff check . && ruff format --check .
python -m pytest
(cd web && npm run lint && npm test -- --maxWorkers=2 && npm run build)

The accepted Cloud Run pilot uses single-writer SQLite with Litestream/GCS recovery. Release promotion requires verified writer drain, compatible migration lineage and recovery; optional email accounts also need working delivery. Follow the existing release checklist. Roles/organisations, shared multi-instance rate limiting and broader grading policies remain roadmap work.