07 Data & Analytics Spec — InvestPlay

Overview

InvestPlay is fundamentally a data-driven education platform. The analytics engine serves three distinct purposes:

For the Student: To provide personal insights and track progress.
For the Teacher/Institution: To prove learning outcomes and identify struggling students.
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?

To monetize insights legally and ethically in the EU, strict boundaries must exist.

Total Anonymization: Data exported for macro reports is stripped of all userId, email, name, and precise location data.
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.
Opt-Out: B2C users have a clear toggle to opt-out of research aggregation.
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.

4.3 KiB Raw Blame History