85 lines
6.5 KiB
Markdown
85 lines
6.5 KiB
Markdown
# 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.
|