admin/InvestPlay
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
a6ed59c74ba4695666bd8b3ca849658a029029c9
InvestPlay/specs/02-system-architecture.md
admin e32afc9bbc Upload files to "specs"
2026-06-12 16:00:04 +00:00

6.5 KiB
Raw Blame History

02 System Architecture — InvestPlay

Overview

InvestPlay follows a Microservices-oriented Monorepo architecture. It relies on a multi-tenant, role-based backend (Node.js/NestJS), an API-first headless CMS for dynamic educational content, and a unified React frontend that compiles to Web, Mobile (Capacitor), and Desktop (Tauri).

The system is designed for high scalability, B2B white-labeling, strict data isolation between institutions, and robust controls over third-party API costs (like AI).

1. Top-Level Architectural Pattern

  • Monorepo Management: Managed via Turborepo or Nx to share TypeScript interfaces, design tokens, UI components, and localization strings across all apps and services.
  • Infrastructure: Containerized via Docker. Deployable to AWS, GCP, or a dedicated VPS environment (e.g., Contabo) via Docker Compose or Kubernetes.
  • Multi-Tenancy: Schema-level or Row-Level Security (RLS) multi-tenancy. Every request is scoped to a tenantId to ensure institutional data isolation.

2. Frontend Layer (Client Apps)

The frontend uses a "Write Once, Run Everywhere" strategy to minimize maintenance overhead while maximizing device reach.

  • Core UI Framework: React (Vite or Next.js) + TypeScript + TailwindCSS.
  • Web App: Standard SPA/SSR React application served via browser.
  • Mobile App (iOS/Android): Wrapped using Capacitor. Provides native device capabilities (push notifications, haptics, biometrics) using the web codebase.
  • Desktop App (Windows/macOS/Linux): Wrapped using Tauri v2. Rust-based, highly performant, and memory-efficient alternative to Electron.
  • State Management: Zustand for global state (auth, active tenant) and React Query / Apollo Client for server state and caching.
  • UI Component Library: Shared internal package built on Radix UI or shadcn/ui for accessible, headless components.

3. Backend Layer (Core API)

The backend handles business logic, real-time simulation streaming, gamification rules, and AI proxying.

  • Core Framework: Node.js with NestJS. Enforces a strict, modular architecture.
  • API Protocol: GraphQL (Primary data fetching) and REST (Webhooks, third-party integrations).
  • Real-Time Protocol: WebSockets (Socket.io) used exclusively for real-time multiplayer classroom simulations, live leaderboards, and AI chat streaming.
  • Background Workers: BullMQ running on Redis for asynchronous tasks (e.g., end-of-day portfolio valuation, weekly email digests, analytics rollup, market tick generation).

Key NestJS Modules

  • AuthModule: Handles JWT generation, SSO mapping, and role guards.
  • TenantModule: Manages institutional settings, white-label UI configs, and feature flags.
  • CurriculumModule: Interfaces with the Headless CMS to serve lessons and track student progress.
  • SimulationModule: The "Time Machine" engine. Broadcasts historical market ticks via WebSockets.
  • PortfolioModule: Executes virtual trades, calculates ROI, ESG scores, and risk metrics.
  • AICoachModule: The secure proxy for LLM requests (enforces token limits, prompt injection).

4. Data Layer

  • Primary Database: PostgreSQL accessed via Prisma ORM. Chosen for strict ACID compliance, relational integrity (essential for ledgers and transactions), and native JSON support (for flexible telemetry metadata).
  • In-Memory Store / Cache: Redis. Handles WebSocket state, active user sessions, API rate-limiting token buckets, and fast-read leaderboards (Sorted Sets).
  • Blob Storage: S3-compatible storage (AWS S3, Cloudflare R2, or MinIO). Stores user avatars, generated PDF reports, and downloaded CSV historical market data.

5. Content Layer (Headless CMS)

Educational content must be separated from application code to allow non-technical curriculum designers to update lessons.

  • CMS Engine: Strapi or Payload CMS.
  • Content Structure: Lessons are built using a Dynamic Block Model. A lesson is a JSON array of components (e.g., [ { type: 'Hero' }, { type: 'Text' }, { type: 'BudgetGame' }, { type: 'Quiz' } ]).
  • Localization: Native i18n support at the CMS level. The frontend requests content using the Accept-Language header.

6. AI Integration & Cost Control Architecture

The AI Coach is a metered, securely proxied service. Client apps never communicate directly with OpenAI or Google Gemini.

  • Proxy Routing: All chat requests hit the NestJS AICoachModule.
  • Context Injection: The backend intercepts the request, appends the user's current virtual portfolio state, recent mistakes, and the specific lesson context into the hidden System Prompt.
  • Rate Limiting (Token Bucket algorithm via Redis):
    • User limit: Max N requests per day.
    • Tenant limit: Max N tokens per month per school.
  • Billing Strategy: If a university exceeds its monthly quota, the backend returns a 429 Too Many Requests or gracefully falls back to static hint systems, unless the institution provides their own API key (Bring-Your-Own-Key mode).

7. Third-Party Integrations

  • Authentication & SSO: Clerk or Auth0. Handles secure JWTs and provides out-of-the-box B2B SAML SSO (so universities can log in with their .edu Microsoft/Google accounts).
  • Transactional Emails: Resend using React Email for templating (Welcome emails, teacher invites, weekly progress reports).
  • B2B Billing: Stripe Connect. Manages institutional SaaS subscriptions (e.g., charging a school based on active student seats).
  • Push Notifications: Firebase Cloud Messaging (FCM) for iOS/Android alerts.
  • Historical Market Data: Yahoo Finance (CSV exports) or Alpha Vantage (EOD APIs) used asynchronously by background workers to seed "Blind Simulation" scenarios.

8. Security & Compliance

  • No Real Money Connectivity: The system explicitly lacks Plaid, Stripe (for B2C), or real brokerage API integrations for students. Decimal types in PostgreSQL represent isolated virtual currency.
  • GDPR Compliance:
    • Soft-delete functionality for all user data.
    • Telemetry and analytics data routed to institutional dashboards is aggregated.
    • Anonymization pipelines strip PII (Personal Identifiable Information) before data is exported for research purposes.
    • AI Prompt sanitization ensures no PII is sent to external LLM providers.
  • API Security: CORS whitelisting, helmet (HTTP headers), JWT payload verification, and GraphQL query depth limiting to prevent Denial of Service (DoS) attacks.