feat: complete Phase 1 foundation scaffold

- Monorepo: Turborepo + pnpm workspaces with 7 apps/packages
- Backend: NestJS scaffold with 9 modules (auth, tenant, curriculum, simulation, portfolio, ai-coach, analytics, classroom, gamification)
- Frontend: React 18 + Vite + TailwindCSS + shadcn/ui with 10 pages, 14 UI primitives, 3 Zustand stores
- Database: Prisma schema with 19 models, 13 enums, seed script, multi-tenant ready
- Docker: Dev, production, and Portainer Compose files with Traefik reverse proxy
- Configuration: .env.example (47 vars), Zod validation, frontend-safe env exposure
- i18n: English + Greek locale files (10 files), ICU MessageFormat, react-i18next
- Shared packages: @investplay/types, @investplay/ui, @investplay/i18n, @investplay/utils
- CI/CD: GitHub Actions (lint, typecheck, test, build, deploy, PR checks)
- Documentation: CONTEXT.md, ARCHITECTURE.md (10 Mermaid diagrams), API.md, LOCALIZATION.md, DEVELOPMENT-ROADMAP.md
- Infrastructure: Dockerfiles (dev + prod), nginx configs, backup/healthcheck scripts
- Security: JWT auth guards, role-based access, rate limiting, Helmet, CORS, PII sanitization

README.md

@@ -0,0 +1,127 @@
+# InvestPlay
+
+**Financial literacy education platform** — Teaching students to invest wisely through interactive simulations, gamified learning, and AI-powered coaching.
+
+## Architecture
+
+InvestPlay is a **Turborepo** monorepo managed with **pnpm** workspaces.
+
+```
+investplay/
+├── apps/
+│   ├── api/          # NestJS backend (REST, GraphQL, WebSocket)
+│   ├── web/          # React + Vite + TailwindCSS frontend
+│   └── cms/          # Payload CMS (content management)
+├── packages/
+│   ├── types/        # @investplay/types — shared TypeScript types
+│   ├── ui/           # @investplay/ui — shared UI components (shadcn/ui)
+│   ├── i18n/         # @investplay/i18n — translations (en, el)
+│   └── utils/        # @investplay/utils — shared utilities
+└── docs/             # Architecture and design documentation
+```
+
+### Tech Stack
+
+| Layer       | Technology                                      |
+| ----------- | ----------------------------------------------- |
+| Monorepo    | Turborepo + pnpm workspaces                    |
+| Backend     | NestJS, Prisma, GraphQL, Socket.io, BullMQ     |
+| Frontend    | React 18, Vite, TailwindCSS, shadcn/ui         |
+| CMS         | Payload CMS                                     |
+| Database    | PostgreSQL (via Prisma)                         |
+| Cache/Queue | Redis, BullMQ                                   |
+| AI          | Azure OpenAI (Managed / BYOK)                  |
+| i18n        | i18next, react-i18next                          |
+| Testing     | Vitest, Playwright, Testing Library             |
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js >= 20
+- pnpm >= 9
+
+### Install
+
+```bash
+pnpm install
+```
+
+### Development
+
+Start all services in development mode:
+
+```bash
+pnpm dev
+```
+
+Or start individual apps:
+
+```bash
+pnpm --filter @investplay/api dev    # API server (port 3001)
+pnpm --filter @investplay/web dev    # Web app (port 3000)
+pnpm --filter @investplay/cms dev    # CMS (port 3002)
+```
+
+### Code Quality
+
+```bash
+pnpm lint        # Lint all packages
+pnpm typecheck   # TypeScript type checking
+pnpm test        # Run all tests
+pnpm format      # Format code with Prettier
+pnpm build       # Build all packages
+```
+
+## Packages
+
+### `@investplay/types`
+Shared TypeScript interfaces and enums for users, tenants, curriculum, simulations, gamification, classrooms, analytics, and AI coaching.
+
+### `@investplay/ui`
+Shared UI component library built on shadcn/ui primitives with TailwindCSS design tokens. Includes utility functions (`cn`, `formatCurrency`, `formatXP`, `formatPercentage`).
+
+### `@investplay/i18n`
+Internationalization layer using i18next. Supports English (`en`) and Greek (`el`) with namespaced translations for UI, finance terms, gamification, classroom management, and AI coach.
+
+### `@investplay/utils`
+Shared utilities: Zod validation schemas, formatting functions (currency, dates, numbers, percentages), and application constants.
+
+## Apps
+
+### API (`apps/api`)
+NestJS backend providing:
+- GraphQL API (Apollo Server)
+- REST endpoints
+- Real-time WebSocket events (Socket.io)
+- Queue-based job processing (BullMQ)
+- Prisma ORM for database access
+
+### Web (`apps/web`)
+React 18 SPA with:
+- Vite for fast development and builds
+- TailwindCSS with InvestPlay design tokens
+- React Router for client-side routing
+- TanStack Query for server state management
+- Zustand for client state
+- Recharts for data visualization
+- Socket.io client for real-time updates
+
+### CMS (`apps/cms`)
+Payload CMS for managing:
+- Curriculum content and lesson blocks
+- Simulation configurations
+- Badges and achievements
+- User and tenant management
+
+## Contributing
+
+1. Create a feature branch: `git checkout -b feat/your-feature`
+2. Make your changes
+3. Run `pnpm lint` and `pnpm typecheck` and `pnpm test`
+4. Commit using conventional commits: `feat:`, `fix:`, `docs:`, etc.
+5. Open a pull request
+
+## License
+
+See [licence.md](./licence.md).