InvestPlay/specs/05-classroom-and-institution-spec.md

05 Classroom & Institution Spec — InvestPlay

Overview

While individual users can use InvestPlay independently, the core B2B value proposition lies in the Institution Layer. This module transforms the app from a single-player game into a managed academic tool. It provides schools, universities, and banks with the tools to manage student cohorts, assign curriculum, run live simulations, and extract measurable learning outcomes.

1. Institutional Hierarchy

The system organizes users into a strict hierarchy to ensure data privacy and clear management structures.

1. Tenant (The Institution): E.g., "University of Athens" or "National Bank of Greece".
2. Tenant Admin: An IT or department head who manages the subscription, white-label settings, AI billing mode, and invites Teachers.
3. Teacher / Instructor: An educator who creates Classrooms, invites Students, assigns lessons, and runs live simulations.
4. Classroom (Cohort): A specific group of students (e.g., "Macroeconomics 101 - Fall 2026").
5. Student: The end-user completing modules and participating in simulations.

2. The Teacher Dashboard

The Teacher Dashboard is a dedicated web interface (not available on mobile) optimized for desktop and projector screens.

Core Capabilities

• Classroom Management: Create cohorts and generate unique, expiring Invite Codes or magic links for students to join.
• Curriculum Assignment: Browse the Headless CMS content library and assign specific Modules or Lessons to a Classroom with due dates.
• Progress Tracking: A visual heatmap showing which students have completed assignments, failed quizzes, or are falling behind.
• Intervention Alerts: Automated flags generated by the telemetry system (e.g., "Warning: 40% of the class failed the Compound Interest quiz" or "Student A has ignored 3 consecutive risk warnings in the simulator").

3. Live Classroom Simulations

This is the flagship multiplayer feature of InvestPlay, designed to be played live during a class or lecture.

The "Time Machine" Event

Teachers can launch a synchronized historical simulation for the entire classroom.

1. Selection: The teacher selects a "Blind Scenario" (e.g., The 2008 Financial Crisis).
2. Waiting Room: Students join the "Lobby" via the mobile app.
3. Execution: The teacher clicks "Start". The NestJS backend begins streaming market ticks via WebSockets to all connected student apps simultaneously.
4. Live Leaderboard: The teacher's dashboard displays a real-time, anonymized leaderboard showing the cohort's aggregate performance and risk metrics as the simulation progresses.
5. The Reveal: At the end of the simulation, the teacher triggers the "Big Reveal," showing the real historical asset and facilitating a class discussion based on the data.

4. Leaderboards & Gamification (B2B Context)

Leaderboards in an educational setting must be handled carefully to avoid discouraging underperforming students or incentivizing reckless gambling.

Classroom Leaderboards

• Opt-in / Anonymized: Teachers can choose to show real names or anonymized avatars on the leaderboard.
• Multi-Metric Ranking: Students are ranked not just by "Highest ROI" (which encourages gambling), but by a Composite Score that factors in:
  • Return on Investment (ROI).
  • Risk Management (e.g., maintaining diversification).
  • ESG Alignment (if applicable to the lesson).
  • Quiz Scores and Lesson Completion.

5. Institutional Reporting & Export

Schools require proof of learning outcomes to justify software budgets.

Automated Reports

• End-of-Session Reports: After a live simulation, the system generates a PDF/CSV report detailing the cohort's average return, common mistakes made, and quiz pass rates.
• Student Report Cards: Individual, printable summaries of a student's progress through the curriculum, suitable for academic grading.
• Tenant-Level Analytics (Admin): Monthly summaries for the Tenant Admin showing total active users, AI token consumption, and aggregate platform engagement.

Data Privacy & Export (GDPR)

• Teachers only have access to data for students explicitly enrolled in their Classrooms.
• Students have the right to request a complete export of their data or request account deletion, compliant with EU regulations.
• Upon graduation or leaving the institution, a student can decouple their account from the Tenant, converting it into a standard B2C personal account while retaining their XP and Badges.