Upload files to "specs"

specs/07-data-and-analytics-spec.md

@@ -0,0 +1,64 @@
+# 07 Data & Analytics Spec — InvestPlay
+
+## Overview
+
+InvestPlay is fundamentally a data-driven education platform. The analytics engine serves three distinct purposes:
+1. **For the Student:** To provide personal insights and track progress.
+2. **For the Teacher/Institution:** To prove learning outcomes and identify struggling students.
+3. **For the Platform (B2B):** To aggregate anonymized behavioral data into macro-level insights (e.g., "The Gen Z Risk Tolerance Report") for research and institutional partners.
+
+This document defines the telemetry architecture, the reporting outputs, and the strict privacy boundaries required for EU/GDPR compliance.
+
+## 1. Behavioral Telemetry (Event Tracking)
+
+The system does not just track *if* a student completed a lesson; it tracks *how* they behave inside simulations. Every major interaction fires an event to the `AnalyticsModule` (stored in PostgreSQL as JSON metadata).
+
+### Key Tracked Events
+- `LESSON_STARTED` / `LESSON_COMPLETED`
+- `QUIZ_ATTEMPTED` (Includes score and specific answers chosen)
+- `SIMULATION_JOINED`
+- `TRADE_EXECUTED` (Includes asset, allocation %, and portfolio context at the time of trade)
+- `RISK_WARNING_SHOWN` (e.g., UI warned student about lack of diversification)
+- `RISK_WARNING_IGNORED` (Student proceeded with the trade anyway)
+- `PANIC_SELL_DETECTED` (Student sold an asset immediately after a sharp drop in a blind scenario)
+- `HYPE_TRAP_TRIGGERED` (Student bought an asset during a simulated finfluencer scam event)
+- `AI_COACH_CONSULTED` (Counts when and why the student asked for help)
+
+## 2. Institutional Reporting (The B2B Value)
+
+Teachers and Tenant Admins require automated, readable proof of efficacy.
+
+### The Teacher Dashboard Analytics
+- **The Cohort Heatmap:** A visual matrix showing the entire classroom. Green = passed module, Yellow = in progress, Red = failed quiz/struggling.
+- **Intervention Feed:** An automated list of suggested actions for the teacher. (e.g., *"3 students failed the 'Compound Interest' quiz. Consider reviewing this topic next class."*)
+
+### Automated Report Generation (PDF/CSV)
+The `AnalyticsModule` runs background jobs to compile session data into downloadable artifacts.
+- **Post-Simulation Report:** After a live "Blind Scenario," the teacher can download a summary showing:
+  - Average class ROI.
+  - The most commonly held asset.
+  - The % of the class that diversified vs. went "all-in."
+  - The % of the class that panic-sold during the injected market crash.
+
+## 3. Macro Insights (The B2B Data Monetization Strategy)
+
+As the user base grows, the aggregated behavioral data of 16-25 year olds becomes highly valuable to universities, financial research centers, and policy makers.
+
+### The "Gen Z Financial Behavior Index"
+InvestPlay can generate quarterly, macro-level reports answering questions like:
+- *Do 18-year-olds prioritize ESG (Environmental, Social, Governance) metrics over pure ROI?*
+- *How resilient is Gen Z to simulated market crashes compared to historical averages?*
+- *What is the baseline budgeting knowledge of high school students before taking the curriculum?*
+
+### GDPR & Privacy Enforcement (Strict Rules)
+To monetize insights legally and ethically in the EU, strict boundaries must exist.
+1. **Total Anonymization:** Data exported for macro reports is stripped of all `userId`, `email`, `name`, and precise location data.
+2. **Aggregation Only:** Reports only deal in cohorts of 50+ users. It must be impossible to trace a data point back to a single individual or a specific school.
+3. **Opt-Out:** B2C users have a clear toggle to opt-out of research aggregation.
+4. **B2B Tenant Controls:** Universities can explicitly stipulate in their SaaS contract that their students' data cannot be included in global aggregated research pools. The platform enforces this via the `Tenant.excludeFromResearch` flag.
+
+## 4. Technical Implementation
+
+- **Storage:** Telemetry events are stored in PostgreSQL using the `JSONB` column type for flexible querying.
+- **Processing:** Raw events are processed nightly by a `BullMQ` worker that rolls them up into daily/weekly aggregated materialized views to ensure the dashboards load instantly.
+- **Data Retention:** Raw user telemetry is soft-deleted or anonymized after 24 months, or immediately upon user account deletion, to comply with GDPR "Right to be Forgotten" mandates.