CLASSROOM
TOKEN
HUB

Project Timeline

How a teacher's side project became Classroom Token Hub v2.0.

Back to Learn More

How we got here

Every release, every crisis, and every lesson, in order. Select an entry to read what changed and why. Use the filters to follow one thread through the whole history.

What if, I just build it myself?

  1. Genesis

    The Original Problem & Design Decisions

    Pre-2024 → November 2025 PhilosophyArchitecture

    The project began as a full-time high school teacher's answer to a gap in educational technology: no platform simulated classroom economies realistically while respecting student data privacy.

    "I will just make it myself."

    Five Core Design Decisions Crystallized:
    • Experience Before Explanation — Students understand systems after feeling them, not from lectures
    • Join Code as Source of Truth — Early designs tied students to teacher accounts and failed in multi-teacher classrooms; join code became the absolute source of class isolation, reshaping the entire data model
    • Teacher Authority with Transparency — No invisible overrides; all teacher actions visible to students
    • Classroom Wage Index (CWI) — Macro-level stabilizer to prevent runaway wages and economic collapse
    • Insurance as Reality Response — Attendance isn't purely a moral choice; punishment disguised as realism is neither accurate nor educational
    The Name Change: "Classroom Economy" → "Classroom Token Hub"

    Not just a rebrand — a philosophical shift from a gimmick to a persistent, interconnected system. A hub for comprehensive financial literacy.

    Key Learning: Real students find real bugs that simulated testing misses. Security must be foundational, not retrofitted.
  2. Pre-Release

    Building the Foundation

    Pre-2024 → 2025 ArchitectureFeatures

    Real classroom testing and iterative development produced the core platform:

    • Modular blueprint architecture (refactored from 4,500-line monolith)
    • 41 SQLAlchemy models with explicit economic state
    • PII encryption at rest (Fernet AES-128-CBC)
    • TOTP 2FA for all admin accounts
    • Password hashing with bcrypt + pepper (layered defense)
    • Multi-tenancy architecture (join_code as source of truth)
    • 55 comprehensive test files
    • 83 Alembic migrations with idempotency helpers
    • Dual accounts: checking + savings with interest
    • Classroom store, hall pass system, insurance policies, rent collection

Oh no, why can I see other classes?

  1. P0 Crisis

    Same-Teacher Multi-Period Data Leak

    November 2025 FixesSecurity
    Impact: Students in multiple class periods with the same teacher saw aggregated financial data across all periods — a fundamental privacy and fairness violation.

    Root Cause:
    • Transaction model had teacher_id but not join_code
    • All queries filtered by teacher_id only, returning data across all periods
    Resolution:
    • Added join_code to all financial tables
    • Updated session management to track current_join_code
    • Modified ALL queries to scope by join_code
    • Created interactive backfill for legacy transactions
    • Added comprehensive multi-tenancy regression tests
    Lesson: Multi-tenancy must be enforced at the database level, not the application level. join_code is non-negotiable.
  2. v1.0.0

    First Stable Release

    November–December 2025 FeaturesArchitecture

    All critical security issues resolved. Production-ready platform.

    Ships with:
    • Multi-tenancy with join-code isolation (P0 fix)
    • Python 3.12+ & SQLAlchemy 2.0+ compatibility (52 deprecated patterns updated)
    • Teacher account recovery (student-verified codes)
    • System admin portal with error logging
    • Comprehensive transaction audit trails
    • Insurance policies (enrollment, claims, reimbursement)
    • Rent collection system
    • TOTP 2FA for all admins
    • Dual accounts (checking + savings with interest)
    • Classroom store with bundles
    • Hall pass system with time tracking
    • PII encryption at rest
  3. v1.1.0

    Analytics & UI Redesign

    December 13, 2025 Features
    • Student Analytics Dashboard — Weekly statistics: days attended, earnings tracking, spending
    • Savings Projection Graph — 12-month interactive growth visualization using Chart.js
    • Long-Term Goal Items — Expensive class rewards exempt from CWI balance checks
    • Economy Health Dashboard — Specific recommended ranges with actionable guidance
    • Complete UI Redesign — Modern card layouts, softer colors, sticky sidebar navigation
  4. v1.1.1

    Security Hardening v1

    December 14–15, 2025 SecurityFixes
    • Secured teacher recovery verification with hashed date-of-birth
    • Hardened student login redirects (UTC-normalized dashboard calculations)
    • Fixed insurance management crashes for legacy forms
    • Added cache-busting static asset helpers
    • Applied green theme consistently to standalone auth pages

Wouldn't it be nice to have that too?

  1. v1.2.0

    PWA, Mobile & Accessibility

    December 18, 2025 FeaturesArchitecture
    • Progressive Web App — Fully installable on iOS/Android with offline fallback
    • Service Worker — Intelligent caching, auto-cleanup, version management
    • Mobile-First Experience — Dedicated templates, bottom tab navigation, 44×44px touch targets
    • WCAG 2.1 AA Accessibility — ARIA labels, enhanced keyboard navigation, improved color contrast, skip-to-content links
    • Terminology Update — "Tap In/Out" → "Start Work/Break Done" for clarity
    Bug Fixed: Multi-tenancy payroll bug leaking calculations across class periods.
  2. v1.2.1

    Legacy Account Migration

    December 21, 2025 ArchitectureFixes
    • Comprehensive migration script: teacher_id → claim-based enrollment
    • 5-phase migration: students, associations, blocks, join codes, related tables
    • Critical: Transaction backfill matches on BOTH student_id AND teacher_id
    • Join code schema audit tool for multi-tenancy compliance
    • Full test coverage for all migration phases
  3. v1.3.0

    Passwordless Auth & Security Audit

    December 25, 2025 SecurityFeatures
    • WebAuthn/FIDO2 Passkey Authentication — YubiKey, Touch ID, Face ID, Windows Hello, synced passkeys; available for teachers and system admins
    • Encrypted TOTP Secrets at Rest — Fernet (AES-128-CBC); database compromise alone insufficient for 2FA
    • Comprehensive Security Audit — 16 findings: 2 critical, 2 high, 3 medium, 4 low, 5 informational
    • PromptPwnd Fixed — Critical AI prompt injection in GitHub Actions (workflow disabled, no exploitation detected)
    • Removed sensitive information (usernames, PII) from application logs
  4. v1.4.0

    Announcements & UI/UX Enhancements

    December 27, 2025 FeaturesSecurity
    • Announcement System — Per-period announcements with rich formatting; global system-admin announcements
    • Personalized Greetings — Time-aware greetings on teacher and student dashboards
    • Accordion Navigation — Collapsible sidebar with Classroom / Economy / Bills / Settings sections
    • Streamlined Authentication Flow — Two-method buttons with smooth TOTP/passkey toggle
    • CodeQL Remediation — 62 security alerts addressed: DOM XSS, TOTP logging, workflow permissions, URL redirection
  5. v1.5.0

    Issue Resolution & Escalation System

    December 29, 2025 Features
    • Student Submission Interface — Knowledge Base, Report Issue, My Issues tabs; automatic context capture (balances, history)
    • Transaction & Attendance Issue Reporting — Report buttons on every transaction and tap event
    • Teacher Review Queue — Resolve via void/adjustment/denial; escalate with diagnostic notes and optional bug-bounty reward
    • Privacy-Conscious Design — Opaque student references (non-reversible hashes) for sysadmin views
    • 4 New Models — Issue, IssueCategory, IssueStatusHistory, IssueResolutionAction
  6. v1.6.0

    Repository Organization & Stability

    January 1, 2026 ArchitectureFixes
    • Consolidated duplicate scripts into scripts/ directory
    • Fixed HallPassSettings NOT NULL multi-tenancy violation
    • Passkey authentication environment variable path fix
    • Getting Started widget: database persistence instead of localStorage (cross-device sync)
    • Comprehensive documentation accuracy fixes (10 inaccuracies corrected)
  7. v1.7.0

    Analytics Dashboard, Rent Itemization & Mobile Nav

    January 9, 2026 FeaturesAnalytics
    • Analytics Dashboard (CWI-Relative Metrics) — Participation rate, money velocity, CWI deviation bands, budget survival; 3 new models; 5-second readability design: "Something is drifting — and I know what lever to pull"
    • Mobile Navigation Enhancement — Floating hamburger with slide-in animation and backdrop overlay; icons-only on mobile
    • Rent Itemization MVP — RentItem model; per-period or per-use purchase duration; optional store integration; itemized breakdown in student view
    • Rent Privilege Badges — Green (rent-covered) and blue (individually purchased) badges on student detail pages
    • ToS Acknowledgment Modal during admin sign-up
  8. Crisis

    The Great Decimal Precision Crisis

    January 2026 Fixes
    Symptoms: Zero-balance transfers triggering $35 overdraft fees • Partial rent payments leaving unpayable tiny balances ($0.0000001) • Dashboard interest calculations crashing with TypeErrors

    Root Cause:
    • Transaction.amount stored as Float instead of Numeric
    • IEEE 754 floating-point: 0.1 + 0.2 ≠ 0.3
    • Mixed Decimal/float arithmetic caused TypeErrors
    Lesson: Financial systems MUST use Decimal type, never Float. Precision errors compound invisibly and become hidden bugs.
  9. v1.7.1

    Decimal Precision — Financial Accuracy Restored

    January 22–25, 2026 Fixes
    • Float → Numeric(12, 2) database migration across all financial models
    • Systematic Decimal refactoring of ALL financial calculations
    • Near-zero balance normalization (|balance| < $0.01 → $0.00)
    • Decimal precision maintained throughout; converts to float only at serialization boundary
    • Fixed savings interest, dashboard earnings/spending, rent calculations
    • All financial calculations now mathematically exact

This is Classroom Token Hub. Your classroom economy, reimagined.

  1. v1.8.0

    Rent Item Types & Coverage Period Tracking

    February 8–9, 2026 FeaturesFixesSecurity
    • Three Rent Item Types:
      • Privilege — Shows badge on roster when rent paid; optionally in store
      • Per-Use — Grants free store redemptions via uses_remaining tracking
      • Hall Pass — Tops off passes via StudentBlock.rent_hall_passes
    • Pre-Paid Coverage Period Tracking — coverage_month/coverage_year on RentPayment; all checks use coverage-based lookups
    • Mid-Period Edit Guardrail — Item type and use limits locked once any student pays; only cosmetic edits allowed
    • Insurance class selector multi-tenancy fix (was aggregating all periods)
    • Grafana proxy XSS protection (case-insensitive MIME blocking)
  2. v1.9.0

    System Admin Redesign & Design System Unification

    March 4, 2026 FeaturesArchitectureFixes

    The work shown here as "in progress" shipped together as v1.9.0.

    • A redesigned system administrator console and one shared design system across teacher, student, and administrator pages
    • Two urgent fixes: an automatic clock-out that could pay a student twice, and rent that could be credited to the wrong period
    • Student personal details are removed once a student claims their account, and account recovery became simpler
    • Expiration dates for class-wide store goals
    • This interactive project timeline
  3. v1.10.0

    The Final Version 1 Release

    June 14, 2026 SecurityFixesFeatures

    The last release of the original app, after months of hardening while version 2 was built alongside it.

    • Student dates of birth were removed entirely after a school district privacy review, with an updated privacy policy and a page for district partners
    • A live health check that watches the rules the app must never break
    • A steadier rent payment flow and recurring insurance billing
    • A notice to teachers that version 1 was coming to an end
  4. Retired

    Version 1 Retires

    July 1, 2026 Philosophy

    Version 1 was retired after a seven-month run in real classrooms. Our own students tested it harder than any test suite could, and what they found shaped everything that came next.

    A final snapshot of the version 1 system was recorded before the move to version 2. Version 2 is a clean break: it does not carry version 1 accounts or data forward.

What if we built it right from the ground up?

Version 2 is a complete rewrite, built alongside version 1 from January 2026. Every rule the app follows was written down first, and the code was made to obey it.

  1. v2 begins

    Starting Over, Alongside Version 1

    January – March 2026 ArchitecturePhilosophy
    • January 15: the first version 2 work began, rebuilding how students, teachers, and classes relate to each other
    • February: a review of every way the classroom economy could break its own rules
    • March 1: the first written invariant, a rule the app must never break, which became the foundation for everything after it
    Key Learning: Patching a system that was never designed for a rule does not make it follow that rule. Version 2 writes the rules first.
  2. Foundations

    One Way to Change Anything

    April – July 2026 ArchitectureSecurity
    • Every change goes through one door. Anything that changes a balance, a bill, or a record goes through a single, audited path. Nothing edits data on the side.
    • Rules come first. Invariants and domain rules are written down and rank above the code. When they disagree, the code is what gets fixed.
    • A new identity model. A person's login is kept separate from their place in each class, so the same student can belong to several classes without any of them seeing the others.
    • Every class is sealed off. Each class is its own boundary, and every record is tied to exactly one class.
    • A real ledger. Every dollar that moves is recorded as a ledger entry, and balances come from the ledger rather than a number stored on the side.

    By July, the old student, teacher, and roster tables were gone, and the database held only the tables version 2 is built on. The version 1 roadmap's multi-teacher repairs became unnecessary: the tables they were meant to fix no longer exist.

Is it really ready?

Before launch, version 2 was judged against its own written rules, then put in front of real users on a live server.

  1. Audit

    The Readiness Audit

    September 3 – 6, 2026 ArchitectureFixesSecurity

    Every part of the app was checked against its written rules, not against what the code happened to do. The audit found eleven problems that had to be fixed before launch, and all eleven were closed within three days. Among them:

    • A change to rent settings could rewrite bills students had already received
    • Payroll could quietly pay the default rate instead of the rate a teacher set
    • The safeguards on deleting a class could be worked around

    By September 5, all ten areas of the app were rated ready.

  2. Status

    A Public Status Page

    September 2026 Features
    • A status page that answers one question: is Classroom Token Hub working right now?
    • It shows which features are working, based on real use of the app, and says so plainly when there is not enough activity to tell
    • Linked from the sign-in pages, the help pages, and the bottom of this site
  3. v2 = main

    Version 2 Becomes the Main Line

    September 7, 2026 Architecture

    Version 2 became the project's main line of development. Version 1 was preserved alongside it, with every past release kept for the record.

  4. Live test

    Testing on a Live Server

    September 19 – 25, 2026 FixesSecurity

    Version 2 went onto a live server and was used the way teachers and students would use it. Every problem found was logged, fixed, and redeployed, often the same day.

    • 78 findings logged by September 23
    • Payroll, the store, transfers, and scheduled payments all balanced to the cent
    • Class isolation held, including an attempt to change another class's data from an old browser tab
    • Bot protection added to public sign-in and sign-up pages, and a student's name removed from the server logs
    Key Learning: Every one of those findings was invisible to the automated tests and visible within minutes of real use. A passing test suite is not a launch signal on its own.
  5. WCAG 2.1

    Accessible on Every Page

    September 23, 2026 Fixes

    Every real page in the app was audited against the WCAG 2.1 A and AA accessibility standards on a live server. The defects found were fixed, and all 88 page templates now pass.

  6. Bills

    Rent and Insurance That Work Like the Real Thing

    September 24 – 25, 2026 FeaturesArchitecture
    • Rent bills arrive early. Students can see and pay next period's rent before it is due. Paying early locks the period in, and its perks start when the period does.
    • Insurance premiums renew. Each premium is billed a few days ahead and paid automatically. If a payment fails, coverage pauses until the student pays it, and nothing that happened in between is covered.
    • Turning a feature off never strands a debt. What a student already owes stays visible and payable.
    • A contract is a contract. A bill keeps the terms it was issued under, even if a teacher changes the settings later.
  7. v2.0

    Launch

    September 26, 2026 Features

    Version 2 went live for real classrooms. Everything from the test period was cleared first, so every class started fresh. See the status page for how the app is doing right now.

In real classrooms

Students started using version 2 every day. The first week found problems no test had, and each one was fixed and written up.

  1. v2.0.1

    Security Release

    September 28, 2026 Security

    A passkey could sign in to an account other than the one it was registered to. The fix makes each passkey sign in only its own account. Everyone was signed out once, and passkeys had to be registered again. Read the published security advisory.

  2. Payroll

    The First Payday Missed Some Work

    September 28 – 29, 2026 Fixes

    Work sessions that were still open when payroll ran were not paid. Payroll now pays finished sessions only, each exactly once. A one-time correction, reviewed and approved by the teacher, paid 79 students what they were owed.

    Key Learning: Money mistakes are fixed in the open. The correction went through the same review a teacher would expect, not a quiet change behind the scenes.
  3. Outage

    Eight Minutes Offline

    September 30, 2026 Fixes

    For eight minutes during class, the site stopped loading. One kind of sign-up request got stuck waiting on itself, and while it waited no one else could get through. No balances or accounts were affected. A stuck request is now cancelled after a few seconds, and the cause was removed.

  4. v2.1.0

    Fair Pay Changes and Reliable Hall Passes

    October 2, 2026 FeaturesFixes

    The first update after launch, built from what the first week in class showed us.

    • Pay changes start on the next payday. When a teacher changes payroll settings, the change applies from the next payday on. Work students have already done is always paid under the settings in place when they did it.
    • Hall-pass approvals work every time. Approving or turning down a hall-pass request no longer fails with a "request not found" message.
    • Removing a student works. Teachers can now remove a student who has already clocked in and worked.
    • A heads-up before payroll is set up. If students start working before a class has payroll set up, the teacher gets a one-time alert.
    • The September 30 outage is behind us. The cause of that outage is removed.

No, we are not about that life

Classroom Token Hub was created as a classroom economy system that fosters responsibility and shared accountability. Flashy features and gamification are antithesis to our design principles. The following features were intentially omitted to preserve the integrity and consistency with our philosophy.

NO XP BARS OR STREAKS Earned wages and time-based pay. We reward consistency through tangible outcomes that students can understand. What we build: Real wages derived from time with real consequences
NO PERFECT ATTENDANCE BONUSES Realign attendance and productivity as baseline expectations while insurance protects against unexpected deviation from baseline. What we build: Insurance system handles legitimate absences and personal lapses in responsibilities
NO INVISIBLE TEACHER OVERRIDES Mysterious teacher action erodes trust in the system and trivializes consequences as "as teacher wishes" What we build: All actions logged and visible to students
NO BEHAVIOR SCORES No engagement ratings or compliance metrics What we build: Neutral logs supporting teacher conversations
NO AI JUDGMENTS OF INTENT No motivation predictions or effort ratings What we build: Neutral logs that don't infer character
NO UNLIMITED CONFIG KNOBS Arbitrary overrides break system coherence What we build : Guardrailed settings that preserve integrity
NO FRICTIONLESS SHORTCUTS When process slows down and forces cognitive engagement, mistakes become rarity What we build: Deliberate processes requiring acknowledgment
NO LEADERBOARDS Public rankings don't belong in classrooms What we build: Private balances protect student dignity
NO NEUTRALITY CLAIM All systems have assumptions, visible assumptions allow for discussions and adjustments while hidden assumptions breed resentment and distrust when they inevitably surface. What we build: Visible assumptions open to class discussion
NO UNSUPERVISED STUDENT ACCESS Teachers should always be the first person to resolve student issues. What we build: Student support tickets are triaged by teacher first, always.

In reflection

The system you are looking at today is conceptualized, designed, built, tested, maintained, and updated by a full-time high school teacher who lives by the motto “I will just make it myself.”

Becoming an app developer was never part of the plan, but rather a side project that has “gone out of hand.” Every feature and design you see today was a product of countless 500 errors, tears, students’ incessant “Mr., it’s not working!”, and, of course, the satisfaction of seeing the puzzle pieces click into place.

This project would not have been possible without the best beta testers in the world: real students. Every impatient double click, negative deposit, “what if I do this instead?”, and middle-of-the-night transaction exposed bugs and vulnerabilities that would have remained silent for now, but would fail loudly in production.

Classroom Token Hub was created to fill the void of a platform that simulates an economy more realistically than what is available on the market. It also functions as a classroom management tool that teaches students personal responsibility. Most of all, it respects data privacy and security like no other. The friction you experience when creating, claiming, and resetting accounts was intentional. Classroom Token Hub does not ask, “How can we defend ourselves?” It was designed to anticipate, “What if the bad actor gets in?”

Welcome to your classroom economy system, reimagined.