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