# Lila

**Learn words. Beat friends.**

Lila is a vocabulary trainer that turns the media you love into language practice. Learn vocabulary from a Shakira song, the first chapter of _Harry Potter_, or an episode of _Breaking Bad_ — then challenge your friends in real-time multiplayer quizzes.

Live at [lilastudy.com](https://lilastudy.com).

---

## Quickstart

```bash
# 1. Clone and install
git clone git@git.lilastudy.com:forgejo-lila/lila.git
cd lila
pnpm install

# 2. Environment
cp .env.example .env

# 3. Start local services (PostgreSQL, Valkey)
docker compose up -d

# 4. Build shared packages
pnpm --filter @lila/shared build
pnpm --filter @lila/db build

# 5. Run migrations
pnpm --filter @lila/db migrate

# 6. Start dev servers
pnpm dev
```

API: `http://localhost:3000` · Web: `http://localhost:5173`

See [DEPLOYMENT.md](documentation/DEPLOYMENT.md) for production infrastructure details.

---

## Documentation Index

| Document                                                       | What you'll find there                                                  |
| -------------------------------------------------------------- | ----------------------------------------------------------------------- |
| [STATUS.md](documentation/STATUS.md)                           | Current state — what's working, what's blocked, what we're building now |
| [BACKLOG.md](documentation/BACKLOG.md)                         | Prioritized task list: now / next / later / changelog                   |
| [ARCHITECTURE.md](documentation/ARCHITECTURE.md)               | Monorepo structure, layered architecture, data flow                     |
| [DECISIONS.md](documentation/DECISIONS.md)                     | Why we chose X over Y — tool choices, schema design, trade-offs         |
| [DATA_PIPELINE.md](documentation/DATA_PIPELINE.md)             | Gemini → SQLite staging → PostgreSQL: flow, current state, phase status |
| [pipeline/design-doc.md](documentation/pipeline/design-doc.md) | Schema design, difficulty model, query patterns, Gemini JSON contract   |
| [pipeline/roadmap.md](documentation/pipeline/roadmap.md)       | Phase plan for the pipeline and schema migration                        |
| [DEPLOYMENT.md](documentation/DEPLOYMENT.md)                   | Hetzner VPS, Caddy, Docker Compose, CI/CD, backups                      |
| [design/GAME_MODES.md](documentation/design/GAME_MODES.md)     | Planned multiplayer and singleplayer game modes                         |
| [archive/](documentation/archive/)                             | Superseded docs — the removed local-LLM pipeline, CEFR voter strategy   |

---

## Stack

| Layer      | Technology                                      |
| ---------- | ----------------------------------------------- |
| Monorepo   | pnpm workspaces                                 |
| Frontend   | React 19, Vite, TanStack Router, Tailwind CSS   |
| Backend    | Node.js, Express, TypeScript, WebSockets (`ws`) |
| Database   | PostgreSQL + Drizzle ORM                        |
| Auth       | Better Auth (Google + GitHub)                   |
| Validation | Zod (shared between frontend and backend)       |
| Testing    | Vitest, supertest                               |
| Deployment | Docker Compose, Caddy, Hetzner VPS              |
| CI/CD      | Forgejo Actions                                 |

---

## Current Status

- ✅ Singleplayer quiz (5 language pairs: en↔it/de/es/fr)
- ✅ Multiplayer lobby + real-time game (2–4 players, simultaneous answers, 15s timer)
- ✅ Auth (Google + GitHub)
- ✅ Live deployment with CI/CD
- 🔄 Rewriting the vocabulary data pipeline around **Gemini** + a sense-based schema
- 🔄 Phase 7 hardening (rate limiting, error boundaries, monitoring)

See [STATUS.md](documentation/STATUS.md) for the full picture.

---

## Repository Structure

```
lila/
├── apps/
│   ├── api/           — Express backend
│   └── web/           — React frontend
├── packages/
│   ├── shared/        — Zod schemas + constants (API/web contract)
│   └── db/            — Drizzle schema, migrations, models, seeding
├── data-pipeline/     — Gemini generation → SQLite staging → PostgreSQL
├── documentation/   — Project docs (this directory)
└── Caddyfile, docker-compose.yml, etc.
```