Upload files to "specs"

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

@@ -0,0 +1,63 @@
+# 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.