# 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).