Files
InvestPlay/specs/01-product-spec.md
2026-06-12 16:00:04 +00:00

358 lines
16 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 01 Product Spec — InvestPlay
## Overview
InvestPlay is a cross-platform financial literacy and life-skills education product for ages 1625, designed for individual learners, schools, universities, educational centers, and institutional partners. The platform uses gamification, simulation, guided lessons, challenges, and an educational AI coach to help users build practical money skills, starting from everyday budgeting and savings and progressing toward investing, risk, macroeconomics, and advanced financial decision-making.[file:1][file:2]
The product is intentionally not a real trading app and not a robo-advisor. It uses only virtual money and simulated decision environments so users can learn safely, make mistakes without financial harm, and understand the consequences of choices before they face them in adult life.[file:2]
## Product Vision
The core mission of InvestPlay is to improve financial literacy for young people by turning financial education from passive theory into active experience. The product is built to counter misinformation, hype-driven decision-making, and shallow “easy money” narratives by teaching structured thinking, personal finance habits, and risk awareness through interactive systems.[file:2]
InvestPlay should become a long-term financial learning platform rather than a single-use stock simulator. Its scope includes money habits, saving, budgeting, banking, rent and living costs, debt, inflation, investing, and more advanced economic concepts for older or more advanced users.[file:2]
## Product Positioning
InvestPlay is positioned as a financial life education platform with investing as one advanced pillar, not as the center of the product. The app combines elements already seen across financial literacy games, life simulations, and student finance platforms, where budgeting, money management, stock simulations, and classroom learning are bundled into one learning experience.[web:82][web:83][web:84][web:85][web:86]
This positioning allows the product to serve both B2C learners and B2B educational buyers. For learners, the value is a safe and engaging way to prepare for adult financial life; for institutions, the value is curriculum delivery, classroom tools, measurable progress, and structured skill development.[file:2][web:83][web:84]
## Target Users
### Primary User Segments
- Students aged 1618 in high school who need foundational literacy in budgeting, banking, savings, and consumer decision-making.[file:2]
- Students aged 1825 in universities, colleges, and early adult life who need more advanced content in investing, debt, financial planning, and economic decision-making.[file:2]
- Teachers, lecturers, and trainers who need structured lesson delivery, assignments, classroom analytics, and challenge-based activities.[file:2]
- Institutional buyers such as schools, universities, educational centers, banks, youth organizations, and financial literacy programs seeking a deployable education platform.[file:2]
### Secondary User Segments
- Individual self-directed learners using a freemium version.[file:2]
- Research and policy organizations interested in anonymized behavioral insights about youth financial literacy trends.
- Financial institutions that may later use the platform for partnerships, educational sponsorships, or post-graduation lead generation, subject to age, consent, and policy controls.
## Platforms
InvestPlay must be delivered as one product across multiple platforms so that it is accessible in schools, on personal devices, and on desktops and laptops used in classrooms.
Required product channels:
- Web application for Chrome, Safari, Firefox, and Edge on desktop and laptop.
- Mobile apps for iOS and Android.
- Desktop-distributed builds for Windows, macOS, and Linux for optional institutional deployment and offline-capable classroom use.
The experience should be consistent across platforms, with responsive design and shared product logic. Platform-specific wrappers are acceptable, but the user should perceive one product ecosystem rather than different apps.
## Core Product Principles
### 1. Education first
The product must always behave as an educational environment, not a recommendation engine. The AI coach, simulations, and all interactive mechanics should help users reason, compare, reflect, and understand trade-offs rather than pushing them toward specific actions or products.[file:2]
### 2. Safe experimentation
All user activity in the learning and investing layers is virtual. Simulations exist so users can fail safely, learn from mistakes, and build maturity before using real financial products.[file:2]
### 3. Life-first, not trading-first
InvestPlay should teach the full spectrum of financial adulthood: spending, rent, savings, emergency funds, subscriptions, debt, banking, taxes, inflation, and long-term planning before exposing users to advanced trading concepts. This principle is critical to avoid building “just another stock app.”[file:2][web:83][web:85][web:86]
### 4. Modular and localizable
The platform must support plug-and-play educational modules, lessons, mini-games, calculators, challenges, and simulations that can be turned on, off, reordered, replaced, or localized without changing application code. Dynamic block-based rendering through React and headless CMS patterns is well aligned with this requirement.[web:87][web:89][web:101]
### 5. Institutional readiness
The product must work for classroom and institutional use from the start, including roles, reporting, assignments, analytics, localization, branding controls, and cohort-based challenges.[file:2]
## Product Scope
InvestPlay includes four product pillars:
### Learn
Structured educational content including lessons, walkthroughs, tutorials, guided reading, concept explainers, glossaries, quizzes, and progression paths from beginner to advanced.
### Play
Mini-games, finance scenarios, challenges, blind simulations, timed exercises, score-based interactions, and gamified learning loops that teach through action rather than passive reading.[web:82][web:83][web:84][web:85]
### Practice
Virtual portfolios, calculators, budget planners, rent and cost-of-living tools, savings planners, interest comparison tools, risk exercises, and decision labs that help users apply knowledge.
### Teach
Teacher dashboards, assignments, classroom cohorts, reporting, progress analytics, leaderboards, curriculum packaging, and institution-specific deployment tools.[file:2][web:83][web:84]
## Major Feature Domains
### A. Financial literacy foundation
This domain covers beginner and early-stage financial skills such as:
- Needs vs wants.
- Budgeting.
- Cash flow.
- Saving habits.
- Emergency funds.
- Banking basics.
- Interest and APY.
- Subscriptions and recurring costs.
- Everyday spending choices.
- Digital payment awareness.
### B. Adult life readiness
This domain extends into practical adulthood topics such as:
- Rent and housing trade-offs.
- Utilities and monthly bills.
- Debt and credit behavior.
- Salary, taxes, and net income.
- Inflation and purchasing power.
- Insurance basics.
- Cost of living.
- Long-term financial planning.
### C. Investing and markets
This domain introduces investment concepts progressively and only after core foundations:
- Risk and return.
- Diversification.
- Stocks.
- ETFs.
- Bonds.
- ESG concepts.
- ROI basics.
- Time horizon and compounding.
- Portfolio building.
- Market behavior and volatility.
- Advanced exposure for universities: forex, rates, macro effects, additional instruments.
### D. Decision-making and anti-hype education
This domain teaches users how to think critically in high-noise environments:
- Scam awareness.
- Social hype and finfluencer influence.
- FOMO and panic selling.
- Risk management.
- Reading incomplete information.
- Acting under uncertainty.
- Behavioral bias awareness.
### E. Classroom and institutional education
This domain supports academic deployment:
- Classroom creation.
- Cohort enrollment.
- Assignments.
- Module activation by institution.
- Analytics and grading support.
- Classroom leaderboards.
- Session-based challenges.
- Institution-specific branding and localization.
## Product Roles
The platform should support the following user roles:
- Student.
- Teacher / Instructor.
- Institution Admin.
- Platform Admin.
- Content Manager / Curriculum Editor.
- Research / Analytics role for approved aggregated reporting.
Each role should have different permissions, content access, reporting access, and feature visibility.
## AI Coach Product Definition
The AI coach is an educational assistant, not a financial advisor. Its purpose is to explain concepts, ask reflective questions, clarify mistakes, provide contextual hints, summarize lessons, and support learning journeys without making decisions for the user.[file:2]
The AI coach should:
- Explain terms in simple or advanced language based on the learner stage.
- Review a users simulation or challenge outcome and explain what happened.
- Recommend which educational module to study next, not which asset to buy.
- Support multilingual conversation where possible.
- Be constrained by clear safety and usage policies.
The AI coach should not:
- Execute trades.
- Give real financial advice.
- Tell users what to buy or sell in real life.
- Behave like a brokerage assistant.
- Expose institutional buyers to uncontrolled AI costs.
### AI Cost Policy
AI is an optional service layer inside the platform and must be tenant-configurable. OpenAI project budgets can be configured and monitored, but reports indicate budget controls may act as alerts rather than absolute hard stops, so InvestPlay must enforce hard limits in its own backend.[web:92][web:93][web:94][web:95]
Google has also added spend and quota controls for Gemini environments, which makes tenant-level provider selection possible, but backend-side caps are still required for predictable costs.[web:97][web:100]
Supported AI operating modes:
- Managed mode: InvestPlay provides AI under product-managed quotas.
- Institution mode: university or institution provides its own AI provider credentials and absorbs costs.
- Disabled mode: AI coach is turned off for that tenant.
Minimum AI controls:
- Per-user daily token limits.
- Per-tenant monthly token limits.
- Per-feature token budgets, for example chat vs lesson summary vs simulation review.
- Hard shutdown when quota is exhausted.
- Audit logs for prompt and token usage metadata.
## Modular Content Strategy
The educational system must be built as a modular content platform rather than fixed app screens. Lessons should be composed from reusable blocks rendered dynamically by the client, which matches established React + headless CMS block-rendering patterns.[web:87][web:89][web:101]
A lesson can include reusable block types such as:
- Intro text.
- Story scenario.
- Video or media.
- Quiz.
- Calculator.
- Reflection prompt.
- Chart analysis.
- Budget game.
- Blind simulation step.
- Teacher note.
- Assignment.
- Summary.
This model must support:
- Reordering blocks.
- Hiding or enabling blocks per tenant.
- Locale-specific content versions.
- Age-stage adaptation.
- Institution-specific curriculum packs.
- Reuse of the same block in multiple lessons or tracks.
## Localization
Localization is a core product requirement, not a later enhancement. The initial release must support at least English and Greek because that aligns with your current market entry goals.[file:2]
Localization requirements:
- All UI text stored as localization strings.
- Long-form educational content localized at CMS level.
- Support for locale-specific examples, currency, tax language, and educational references.
- Tenant default locale setting.
- User-level language preference override.
- Ability to add future EU locales without rewriting lesson logic.
## Gamification Model
Gamification is central to product engagement, but it must reinforce learning outcomes rather than addictive loops. The platform concept already includes challenges, achievements, leaderboards, and AI-guided feedback in a virtual-money environment.[file:2]
Core gamification elements:
- XP and level progression.
- Badges and achievements.
- Streaks.
- Lesson completion rewards.
- Challenge scoring.
- Classroom and event leaderboards.
- Time-based and scenario-based events.
- Unlockable advanced modules.
Gamification should reward:
- Good reasoning.
- Responsible risk management.
- Lesson completion.
- Reflection and learning consistency.
- Diversification and safe habits where applicable.
Gamification should not reward only:
- Maximum returns.
- Reckless risk.
- Short-term speculation.
## Simulations and Challenges
The product should support multiple challenge types, including blind historical simulations, budgeting games, trade-off scenarios, and life-finance decision labs. Life-simulation and finance game examples in the market show that budgeting and unexpected-life-event simulation formats are especially effective for teaching practical financial behavior.[web:82][web:83][web:85][web:86]
Simulation types should include:
- Budget challenge.
- Emergency fund scenario.
- Cost-of-living planner.
- Blind asset scenario.
- Market crash scenario.
- Rent vs transport trade-off.
- Savings habit challenge.
- ESG portfolio challenge.
- Interest and APY comparison game.
- Debt repayment strategy challenge.
## Data and Analytics Product Requirements
The platform should capture educational and behavioral data to improve teaching, personalization, and reporting. Data collection should serve product learning outcomes, institutional reporting, and anonymized aggregate research outputs where permitted.
Data domains include:
- Lesson completion.
- Quiz performance.
- Time spent.
- Challenge attempts.
- Challenge scores.
- Repeat mistakes.
- Risk warning interactions.
- Leaderboard performance.
- Session attendance.
- AI coach usage.
- Module progression.
A core product rule is that analytics for external research or commercial insight must be anonymized and aggregated before being shared.
## Business Model Support
The product should be designed to support multiple business modes at once:
- Freemium B2C learning tier for individuals.[file:2]
- B2B SaaS licensing for schools, universities, educational centers, and institutional programs.[file:2]
- White-label deployments for institutional buyers.
- Optional AI usage plans by tenant.
- Premium curriculum packs for advanced topics.
- Future partner pathways for post-18 users, subject to trust, compliance, and product boundaries.
## Non-Goals
The product is not intended to be:
- A real broker.
- A trading signal provider.
- A copy-trading or social trading app.
- A fully autonomous financial assistant.
- A crypto speculation-first platform.
- A narrow portfolio game with no broader life-finance education.
## Success Criteria
The production product should be considered successful when it can:
- Deliver financial education across web and mobile in a unified system.
- Support both self-learners and institutions in the same core platform.
- Localize curriculum and UI cleanly for multiple markets.
- Allow modular lessons and challenge systems to be added or removed without app rewrites.
- Provide measurable classroom and learner outcomes.
- Use AI safely and cost-effectively under configurable tenant controls.
- Position itself clearly as a financial adulthood education platform rather than another trading app.
## Product Summary
InvestPlay is a modular, cross-platform financial education ecosystem for young people that combines lessons, mini-games, simulations, classroom tools, and a constrained educational AI coach. It is designed to teach money habits, adult life decisions, and progressively advanced financial concepts through safe virtual practice, with strong support for institutions, localization, and long-term curriculum growth.[file:1][file:2][web:83][web:84]