lila/documentation/mvp.md

glossa mvp

This document is the single source of truth for the project. It is written to be handed to any LLM as context. It contains the project vision, the current MVP scope, the tech stack, the working methodology, and the roadmap.

---

1. Project Overview

A vocabulary trainer for English–Italian words. The quiz format is Duolingo-style: one word is shown as a prompt, and the user picks the correct translation from four choices (1 correct + 3 distractors of the same part-of-speech). The long-term vision is a multiplayer competitive game, but the MVP is a polished singleplayer experience.

The core learning loop: Show word → pick answer → see result → next word → final score

The vocabulary data comes from WordNet + the Open Multilingual Wordnet (OMW). A one-time Python script extracts English–Italian noun pairs and seeds the database. The data model is language-pair agnostic by design — adding a new language later requires no schema changes.

---

2. What the Full Product Looks Like (Long-Term Vision)

• Users log in via Google or GitHub (OpenAuth)
• Singleplayer mode: 10-round quiz, score screen
• Multiplayer mode: create a room, share a code, 2–4 players answer simultaneously in real time, live scores, winner screen
• 1000+ English–Italian nouns seeded from WordNet

This is documented in spec.md and the full roadmap.md. The MVP deliberately ignores most of it.

---

3. MVP Scope

Goal: A working, presentable singleplayer quiz that can be shown to real people.

What is IN the MVP

• Vocabulary data in a PostgreSQL database (already seeded)
• REST API that returns quiz terms with distractors
• Singleplayer quiz UI: 10 questions, answer feedback, score screen
• Clean, mobile-friendly UI (Tailwind + shadcn/ui)
• Local dev only (no deployment for MVP)

What is CUT from the MVP

Feature	Why cut
Authentication (OpenAuth)	No user accounts needed for a demo
Multiplayer (WebSockets, rooms)	Core quiz works without it
Valkey / Redis cache	Only needed for multiplayer room state
Deployment to Hetzner	Ship to people locally first
User stats / profiles	Needs auth
Testing suite	Add after the UI stabilises

These are not deleted from the plan — they are deferred. The architecture is already designed to support them. See Section 9 (Post-MVP Ladder).

---

4. Technology Stack

The monorepo structure and tooling are already set up (Phase 0 complete). This is the full stack — the MVP uses a subset of it.

Layer	Technology	MVP?
Monorepo	pnpm workspaces	✅
Frontend	React 18, Vite, TypeScript	✅
Routing	TanStack Router	✅
Server state	TanStack Query	✅
Client state	Zustand	✅
Styling	Tailwind CSS + shadcn/ui	✅
Backend	Node.js, Express, TypeScript	✅
Database	PostgreSQL + Drizzle ORM	✅
Validation	Zod (shared schemas)	✅
Auth	OpenAuth (Google + GitHub)	❌ post-MVP
Realtime	WebSockets (ws library)	❌ post-MVP
Cache	Valkey	❌ post-MVP
Testing	Vitest, React Testing Library	❌ post-MVP
Deployment	Docker Compose, Hetzner, Nginx	❌ post-MVP

Repository Structure (actual, as of Phase 1 data pipeline complete)

vocab-trainer/
├── apps/
│   ├── api/
│   │   └── src/
│   │       ├── app.ts        # createApp() factory — routes registered here
│   │       └── server.ts     # calls app.listen()
│   └── web/
│       └── src/
│           ├── routes/
│           │   ├── __root.tsx
│           │   ├── index.tsx  # placeholder landing page
│           │   └── about.tsx
│           ├── main.tsx
│           └── index.css
├── packages/
│   ├── shared/
│   │   └── src/
│   │       ├── index.ts      # empty — Zod schemas go here next
│   │       └── constants.ts
│   └── db/
│       ├── drizzle/          # migration SQL files
│       └── src/
│           ├── db/schema.ts          # full Drizzle schema
│           ├── seeding-datafiles.ts  # seeds terms + translations
│           ├── generating-deck.ts    # builds curated decks
│           └── index.ts
├── documentation/            # all project docs live here
│   ├── spec.md
│   ├── roadmap.md
│   ├── decisions.md
│   ├── mvp.md                # this file
│   └── CLAUDE.md
├── scripts/
│   ├── extract-en-it-nouns.py
│   └── datafiles/en-it-noun.json
├── docker-compose.yml
└── pnpm-workspace.yaml

What does not exist yet (to be built in MVP phases):

• apps/api/src/routes/ — no route handlers yet
• apps/api/src/services/ — no business logic yet
• apps/api/src/repositories/ — no DB queries yet
• apps/web/src/components/ — no UI components yet
• apps/web/src/stores/ — no Zustand store yet
• apps/web/src/lib/api.ts — no TanStack Query wrappers yet
• packages/shared/src/schemas/ — no Zod schemas yet

packages/shared is the contract between frontend and backend. All request/response shapes are defined there as Zod schemas — never duplicated.

---

5. Data Model (relevant tables for MVP)

export const terms = pgTable(
  "terms",
  {
    id: uuid().primaryKey().defaultRandom(),
    synset_id: text().unique().notNull(),
    pos: varchar({ length: 20 }).notNull(),
    created_at: timestamp({ withTimezone: true }).defaultNow().notNull(),
  },
  (table) => [
    check(
      "pos_check",
      sql`${table.pos} IN (${sql.raw(SUPPORTED_POS.map((p) => `'${p}'`).join(", "))})`,
    ),
    index("idx_terms_pos").on(table.pos),
  ],
);

export const translations = pgTable(
  "translations",
  {
    id: uuid().primaryKey().defaultRandom(),
    term_id: uuid()
      .notNull()
      .references(() => terms.id, { onDelete: "cascade" }),
    language_code: varchar({ length: 10 }).notNull(),
    text: text().notNull(),
    created_at: timestamp({ withTimezone: true }).defaultNow().notNull(),
  },
  (table) => [
    unique("unique_translations").on(
      table.term_id,
      table.language_code,
      table.text,
    ),
    index("idx_translations_lang").on(table.language_code, table.term_id),
  ],
);

export const decks = pgTable(
  "decks",
  {
    id: uuid().primaryKey().defaultRandom(),
    name: text().notNull(),
    description: text(),
    source_language: varchar({ length: 10 }).notNull(),
    validated_languages: varchar({ length: 10 }).array().notNull().default([]),
    is_public: boolean().default(false).notNull(),
    created_at: timestamp({ withTimezone: true }).defaultNow().notNull(),
  },
  (table) => [
    check(
      "source_language_check",
      sql`${table.source_language} IN (${sql.raw(SUPPORTED_LANGUAGE_CODES.map((l) => `'${l}'`).join(", "))})`,
    ),
    check(
      "validated_languages_check",
      sql`validated_languages <@ ARRAY[${sql.raw(SUPPORTED_LANGUAGE_CODES.map((l) => `'${l}'`).join(", "))}]::varchar[]`,
    ),
    check(
      "validated_languages_excludes_source",
      sql`NOT (${table.source_language} = ANY(${table.validated_languages}))`,
    ),
    unique("unique_deck_name").on(table.name, table.source_language),
  ],
);

export const deck_terms = pgTable(
  "deck_terms",
  {
    deck_id: uuid()
      .notNull()
      .references(() => decks.id, { onDelete: "cascade" }),
    term_id: uuid()
      .notNull()
      .references(() => terms.id, { onDelete: "cascade" }),
    added_at: timestamp({ withTimezone: true }).defaultNow().notNull(),
  },
  (table) => [primaryKey({ columns: [table.deck_id, table.term_id] })],
);

The seed + deck-build scripts have already been run. Data exists in the database.

---

6. API Endpoints (MVP)

All endpoints prefixed /api. Schemas live in packages/shared and are validated with Zod on both sides.

Method	Path	Description
GET	/api/health	Health check (already done)
GET	/api/language-pairs	List active language pairs
GET	/api/decks	List available decks
GET	/api/decks/:id/terms	Fetch terms with distractors for a quiz

Distractor Logic

The QuizService picks 3 distractors server-side:

• Same part-of-speech as the correct answer
• Never the correct answer
• Never repeated within a session

---

7. Frontend Structure (MVP)

apps/web/src/
├── routes/
│   ├── index.tsx             # Landing page / mode select
│   └── singleplayer/
│       └── index.tsx         # The quiz
├── components/
│   ├── quiz/
│   │   ├── QuestionCard.tsx  # Prompt word + 4 answer buttons
│   │   ├── OptionButton.tsx  # idle / correct / wrong states
│   │   └── ScoreScreen.tsx   # Final score + play again
│   └── ui/                   # shadcn/ui wrappers
├── stores/
│   └── gameStore.ts          # Zustand: question index, score, answers
└── lib/
    └── api.ts                # TanStack Query fetch wrappers

State Management

TanStack Query handles fetching quiz data from the API. Zustand handles the local quiz session (current question index, score, selected answers). There is no overlap between the two.

---

8. Working Methodology

Read this section before asking for help with any task.

This project is a learning exercise. The goal is to understand the code, not just to ship it.

How tasks are structured

The roadmap (Section 10) lists broad phases. When work starts on a phase, it gets broken into smaller, concrete subtasks with clear done-conditions before any code is written.

How to use an LLM for help

When asking an LLM for help:

1. Paste this document (or the relevant sections) as context
2. Describe what you're working on and what specifically you're stuck on
3. Ask for hints, not solutions. Example prompts:
   • "I'm trying to implement X. My current approach is Y. What am I missing conceptually?"
   • "Here is my code. What would you change about the structure and why?"
   • "Can you point me to the relevant docs for Z?"

Refactoring workflow

After completing a task or a block of work:

1. Share the current state of the code with the LLM
2. Ask: "What would you refactor here, and why? Don't show me the code — point me in the right direction and link relevant documentation."
3. The LLM should explain the what and why, link to relevant docs/guides, and let you implement the fix yourself

The LLM should never write the implementation for you. If it does, ask it to delete it and explain the concept instead.

Decisions log

Keep a decisions.md file in the root. When you make a non-obvious choice (a library, a pattern, a trade-off), write one short paragraph explaining what you chose and why. This is also useful context for any LLM session.

---

9. Game Mechanics

• Format: source-language word prompt + 4 target-language choices
• Distractors: same POS, server-side, never the correct answer, no repeats in a session
• Session length: 10 questions
• Scoring: +1 per correct answer (no speed bonus for MVP)
• Timer: none in singleplayer MVP
• No auth required: anonymous users

---

10. MVP Roadmap

Tasks are written at a high level. When starting a phase, break it into smaller subtasks before writing any code.

Current Status

Phase 0 (Foundation) — ✅ Complete Phase 1 (Vocabulary Data) — 🔄 Data pipeline complete. API layer is the immediate next step.

What is already in the database:

• 999 unique English terms (nouns), fully seeded from WordNet/OMW
• 3171 term IDs resolved (higher than word count due to homonyms)
• Full Italian translation coverage (3171/3171 terms)
• Decks created and populated via packages/db/src/generating-decks.ts
• 34 words from the source wordlist had no WordNet match (expected, not a bug)

---

Phase 1 — Finish the API Layer

Goal: The frontend can fetch quiz data from the API.

Done when: GET /api/decks/1/terms?limit=10 returns 10 terms, each with 3 distractors of the same POS attached.

Broadly, what needs to happen:

• Define Zod response schemas in packages/shared for terms, decks, and language pairs
• Implement a repository layer that queries the DB for terms belonging to a deck
• Implement a service layer that attaches distractors to each term (same POS, no duplicates, no correct answer included)
• Wire up the REST endpoints (GET /language-pairs, GET /decks, GET /decks/:id/terms)
• Manually test the endpoints (curl or a REST client like Bruno/Insomnia)

Key concepts to understand before starting:

• Drizzle ORM query patterns (joins, where clauses)
• The repository pattern (data access separated from business logic)
• Zod schema definition and inference
• How pnpm workspace packages reference each other

---

Phase 2 — Singleplayer Quiz UI

Goal: A user can complete a full 10-question quiz in the browser.

Done when: User visits /singleplayer, answers 10 questions, sees a score screen, and can play again.

Broadly, what needs to happen:

• Build the QuestionCard component (prompt word + 4 answer buttons)
• Build the OptionButton component with three visual states: idle, correct, wrong
• Build the ScoreScreen component (score summary + play again)
• Implement a Zustand store to track quiz session state (current question index, score, whether an answer has been picked)
• Wire up TanStack Query to fetch terms from the API on mount
• Create the /singleplayer route and assemble the components
• Handle the between-question transition (brief delay showing result → next question)

Key concepts to understand before starting:

• TanStack Query: useQuery, loading/error states
• Zustand: defining a store, reading and writing state from components
• TanStack Router: defining routes, navigating between them
• React component composition
• Controlled state for the answer selection (which button is selected, when to lock input)

---

Phase 3 — UI Polish

Goal: The app looks good enough to show to people.

Done when: The quiz is usable on mobile, readable on desktop, and has a coherent visual style.

Broadly, what needs to happen:

• Apply Tailwind utility classes and shadcn/ui components consistently
• Make the layout mobile-first (touch-friendly buttons, readable font sizes)
• Add a simple landing page (/) with a "Start Quiz" button
• Add loading and error states for the API fetch
• Visual feedback on correct/wrong answers (colour, maybe a brief animation)
• Deck selection: let the user pick a deck from a list before starting

Key concepts to understand before starting:

• Tailwind CSS utility-first approach
• shadcn/ui component library and how to add components
• Responsive design with Tailwind breakpoints
• CSS transitions for simple animations

---

11. Key Technical Decisions

These are the non-obvious decisions already made. Any LLM helping with this project should be aware of them and not suggest alternatives without good reason.

Architecture

Express app: factory function pattern app.ts exports createApp(). server.ts imports it and calls .listen(). This keeps tests isolated — a test can import the app without starting a server.

Layered architecture: routes → services → repositories Business logic lives in services, not route handlers or repositories. Each layer only talks to the layer directly below it. For the MVP API, this means:

• routes/ — parse request, call service, return response
• services/ — business logic (e.g. attaching distractors)
• repositories/ — all DB queries live here, nowhere else

Shared Zod schemas in packages/shared All request/response shapes are defined once as Zod schemas in packages/shared and imported by both apps/api and apps/web. Types are inferred from schemas (z.infer<typeof Schema>), never written by hand.

Data Model

Decks separate from terms (not frequency-rank filtering) Terms are raw WordNet data. Decks are curated lists. This separation exists because WordNet frequency data is unreliable for learning — common chemical element symbols ranked highly, for example. Bad words are excluded at the deck level, not filtered from terms.

Deck language model: source_language + validated_languages array A deck is not tied to a single language pair. source_language is the language the wordlist was curated from. validated_languages is an array of target languages with full translation coverage — calculated and updated by the deck generation script on every run.

Tooling

Drizzle ORM (not Prisma): No binary, no engine. Queries map closely to SQL. Works naturally with Zod. Migrations are plain SQL files.

tsx as TypeScript runner (not ts-node): Faster, zero config, uses esbuild. Does not type-check — that is handled by tsc and the editor.

pnpm workspaces (not Turborepo): Two apps don't need the extra build caching complexity.

---

12. Post-MVP Ladder

These phases are deferred but planned. The architecture already supports them.

Phase	What it adds
Auth	OpenAuth (Google + GitHub), JWT middleware, user rows in DB
User Stats	Games played, score history, profile page
Multiplayer Lobby	Room creation, join by code, WebSocket connection
Multiplayer Game	Simultaneous answers, server timer, live scores, winner screen
Deployment	Docker Compose prod config, Nginx, Let's Encrypt, Hetzner VPS
Hardening	Rate limiting, error boundaries, CI/CD, DB backups

Each of these maps to a phase in the full roadmap.md.

---

13. Definition of Done (MVP)

• GET /api/decks/:id/terms returns terms with correct distractors
• User can complete a 10-question quiz without errors
• Score screen shows final result and a play-again option
• App is usable on a mobile screen
• No hardcoded data — everything comes from the database