# 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.