From 69d4cfde972a369ed6a0d975cb41d35a761c287c Mon Sep 17 00:00:00 2001 From: lila Date: Wed, 15 Apr 2026 04:50:47 +0200 Subject: [PATCH 1/8] adding build step to dev script --- apps/api/package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apps/api/package.json b/apps/api/package.json index 155b859..60fd85a 100644 --- a/apps/api/package.json +++ b/apps/api/package.json @@ -4,7 +4,7 @@ "private": true, "type": "module", "scripts": { - "dev": "tsx watch src/server.ts", + "dev": "pnpm --filter shared build && pnpm --filter db build && tsx watch src/server.ts", "build": "tsc", "start": "node dist/src/server.js", "test": "vitest" From 8d3587683872b355cc2ed4e9f39a6ea30814cc24 Mon Sep 17 00:00:00 2001 From: lila Date: Wed, 15 Apr 2026 04:51:06 +0200 Subject: [PATCH 2/8] not needed anymore --- docker-compose.prod.yml | 91 ----------------------------------------- 1 file changed, 91 deletions(-) delete mode 100644 docker-compose.prod.yml diff --git a/docker-compose.prod.yml b/docker-compose.prod.yml deleted file mode 100644 index 92135eb..0000000 --- a/docker-compose.prod.yml +++ /dev/null @@ -1,91 +0,0 @@ -services: - caddy: - container_name: lila-caddy - image: caddy:2-alpine - ports: - - "80:80" - - "443:443" - volumes: - - ./Caddyfile:/etc/caddy/Caddyfile - - caddy_data:/data - - caddy_config:/config - restart: unless-stopped - depends_on: - api: - condition: service_healthy - networks: - - lila-network - - api: - container_name: lila-api - build: - context: . - dockerfile: ./apps/api/Dockerfile - target: runner - env_file: - - .env - restart: unless-stopped - healthcheck: - test: - ["CMD-SHELL", "wget -qO- http://localhost:3000/api/health || exit 1"] - interval: 5s - timeout: 3s - retries: 5 - depends_on: - database: - condition: service_healthy - networks: - - lila-network - - web: - container_name: lila-web - build: - context: . - dockerfile: ./apps/web/Dockerfile - target: production - args: - VITE_API_URL: https://api.lilastudy.com - restart: unless-stopped - networks: - - lila-network - - database: - container_name: lila-database - image: postgres:18.3-alpine3.23 - env_file: - - .env - environment: - - PGDATA=/var/lib/postgresql/data - volumes: - - lila-db:/var/lib/postgresql/data - restart: unless-stopped - healthcheck: - test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"] - interval: 5s - timeout: 5s - retries: 5 - networks: - - lila-network - - forgejo: - container_name: lila-forgejo - image: codeberg.org/forgejo/forgejo:11 - volumes: - - forgejo-data:/data - environment: - - USER_UID=1000 - - USER_GID=1000 - ports: - - "2222:22" - restart: unless-stopped - networks: - - lila-network - -networks: - lila-network: - -volumes: - lila-db: - caddy_data: - caddy_config: - forgejo-data: From 1b02f6ce8ecb84aeddd78e54f14104125bd58ae9 Mon Sep 17 00:00:00 2001 From: lila Date: Wed, 15 Apr 2026 04:52:29 +0200 Subject: [PATCH 3/8] adding packages db volume --- docker-compose.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/docker-compose.yml b/docker-compose.yml index 5903fa6..e5deed4 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -42,6 +42,7 @@ services: volumes: - ./apps/api:/app/apps/api # Hot reload API code - ./packages/shared:/app/packages/shared # Hot reload shared + - ./packages/db:/app/packages/db - /app/node_modules restart: unless-stopped healthcheck: From 2cb16ed5f0b66eb45f0120bba56b91c17dbd7894 Mon Sep 17 00:00:00 2001 From: lila Date: Wed, 15 Apr 2026 04:52:42 +0200 Subject: [PATCH 4/8] adding note --- documentation/notes.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/documentation/notes.md b/documentation/notes.md index 7d1b801..48673c8 100644 --- a/documentation/notes.md +++ b/documentation/notes.md @@ -17,6 +17,10 @@ WARNING! Your credentials are stored unencrypted in '/home/languagedev/.docker/c Configure a credential helper to remove this warning. See https://docs.docker.com/go/credential-store/ +### docker containers on startup? + +laptop: verify if docker containers run on startup (they shouldnt) + ### vps setup - monitoring and logging (eg via chrootkit or rkhunter, logwatch/monit => mails daily with summary) From fef7c82a3e008300e9353bb855ac4cded3e27c7f Mon Sep 17 00:00:00 2001 From: lila Date: Wed, 15 Apr 2026 05:07:52 +0200 Subject: [PATCH 5/8] adding volumes --- docker-compose.yml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docker-compose.yml b/docker-compose.yml index e5deed4..b661975 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -47,7 +47,7 @@ services: restart: unless-stopped healthcheck: test: - ["CMD-SHELL", "wget -qO- http://localhost:3000/api/health || exit 1"] + ["CMD-SHELL", "wget -qO- http://localhost:3000/api/v1/health || exit 1"] interval: 5s timeout: 3s retries: 5 @@ -67,6 +67,7 @@ services: - "5173:5173" volumes: - ./apps/web:/app/apps/web # Hot reload: local edits reflect immediately + - ./packages/shared:/app/packages/shared - /app/node_modules # Protect container's node_modules from being overwritten environment: - VITE_API_URL=http://localhost:3000 From fbc611c49fe2d8a26d0879b1da38216295812ca4 Mon Sep 17 00:00:00 2001 From: lila Date: Wed, 15 Apr 2026 05:16:29 +0200 Subject: [PATCH 6/8] updating docs --- documentation/decisions.md | 68 ++++++++++++++++++++++++ documentation/notes.md | 13 ++--- documentation/roadmap.md | 95 +++++++++++++++++++++++++-------- documentation/spec.md | 104 +++++++++++++++++++++++++------------ 4 files changed, 216 insertions(+), 64 deletions(-) diff --git a/documentation/decisions.md b/documentation/decisions.md index 4b705c0..cdf41b3 100644 --- a/documentation/decisions.md +++ b/documentation/decisions.md @@ -359,3 +359,71 @@ All deferred post-MVP, purely additive (new tables referencing existing `terms`) - `noun_forms` — gender, singular, plural, articles per language (source: Wiktionary) - `verb_forms` — conjugation tables per language (source: Wiktionary) - `term_pronunciations` — IPA and audio URLs per language (source: Wiktionary / Forvo) + +--- + +## Deployment + +### Reverse proxy: Caddy (not Nginx, not Traefik) + +Caddy provides automatic HTTPS via Let's Encrypt with zero configuration beyond specifying domain names. The entire Caddyfile is ~10 lines. Nginx would require manual certbot setup and more verbose config. Traefik's auto-discovery of Docker containers (via labels) is powerful but overkill for a stable three-service stack where routing rules never change. Caddy runs as a Docker container alongside the app — no native install. + +### Subdomain routing (not path-based) + +`lilastudy.com` serves the frontend, `api.lilastudy.com` serves the API, `git.lilastudy.com` serves Forgejo. Cleaner separation than path-based routing — any service can be moved to a different server just by changing DNS. Requires CORS configuration since the browser sees different origins, and cross-subdomain cookies via `COOKIE_DOMAIN=.lilastudy.com`. Wildcard DNS (`*.lilastudy.com`) means new subdomains require no DNS changes. + +### Frontend served by nginx:alpine (not Node, not Caddy) + +Vite builds to static files. Serving them with nginx inside the container is lighter than running a Node process and keeps the container at ~7MB. Caddy could serve them directly, but using a separate container maintains the one-service-per-container principle and keeps Caddy's config purely about routing. + +### SPA fallback via nginx `try_files` + +Without `try_files $uri $uri/ /index.html`, refreshing on `/play` returns 404 because there's no actual `play` file. Nginx serves `index.html` for all routes and lets TanStack Router handle client-side routing. + +### Forgejo as git server + container registry (not GitHub, not Docker Hub) + +Keeps everything self-hosted on one VPS. Forgejo's built-in package registry doubles as a container registry, eliminating a separate service. Git push and image push go to the same server. + +### Forgejo SSH on port 2222 (not 22) + +Port 22 is the VPS's own SSH. Mapping Forgejo's SSH to 2222 avoids conflicts. Dev laptop `~/.ssh/config` maps `git.lilastudy.com` to port 2222 so git commands work without specifying the port every time. + +### `packages/db` and `packages/shared` exports: compiled JS paths + +Exports in both package.json files point to `./dist/src/index.js`, not TypeScript source. In dev, `tsx` can run TypeScript, but in production Node cannot. This means packages must be built before the API starts in dev — acceptable since these packages change infrequently. Alternative approaches (conditional exports, tsconfig paths) were considered but added complexity for no practical benefit. + +### Environment-driven config for production vs dev + +CORS origin, Better Auth base URL, cookie domain, API URL, and OAuth credentials are all read from environment variables with localhost fallbacks. The same code runs in both environments without changes. `VITE_API_URL` is the exception — it's baked in at build time via Docker build arg because Vite replaces `import.meta.env` at compile time, not runtime. + +### Cross-subdomain cookies + +Better Auth's `defaultCookieAttributes` sets `domain: .lilastudy.com` in production (from env var `COOKIE_DOMAIN`). Without this, the auth cookie scoped to `api.lilastudy.com` wouldn't be sent on requests from `lilastudy.com`. The leading dot makes the cookie valid across all subdomains. + +--- + +## CI/CD + +### Forgejo Actions with SSH deploy (not webhooks, not manual) + +CI builds images natively on the ARM64 VPS (no QEMU cross-compilation). The runner uses the host's Docker socket to build. After pushing to the registry, the workflow SSHs into the VPS to pull and restart containers. Webhooks were considered but add an extra listener service to maintain and secure. Manual deploy was the initial approach but doesn't scale with frequent pushes. + +### Dedicated CI SSH key + +A separate `ci-runner` SSH key pair (not the developer's personal key) is used for CI deploys. The private key is stored in Forgejo's secrets. If compromised, only this key needs to be revoked — the developer's access is unaffected. + +### Runner config: `docker_host: "automount"` + `valid_volumes` + explicit config path + +The Forgejo runner's `automount` setting mounts the host Docker socket into job containers. `valid_volumes` must include `/var/run/docker.sock` or the mount is blocked. The runner command must explicitly reference the config file (`-c /data/config.yml`) — without this flag, config changes are silently ignored. `--group-add 989` in container options adds the host's docker group so job containers can access the socket. + +### Docker CLI installed per job (not baked into runner image) + +The job container (`node:24-bookworm`) doesn't include Docker CLI. It's installed via `apt-get install docker.io` as the first workflow step. This adds ~20 seconds per run but avoids maintaining a custom runner image. The CLI sends commands through the mounted socket to the host's Docker engine. + +--- + +## Backups + +### pg_dump cron + dev laptop sync (not WAL archiving, not managed service) + +Daily compressed SQL dumps with 7-day retention. Dev laptop auto-syncs new backups on login via rsync. Simple, portable, sufficient for current scale. WAL archiving gives point-in-time recovery but is complex to set up. Offsite storage (Hetzner Object Storage) is the planned next step — backups on the same VPS don't protect against VPS failure. diff --git a/documentation/notes.md b/documentation/notes.md index 48673c8..c750683 100644 --- a/documentation/notes.md +++ b/documentation/notes.md @@ -11,6 +11,10 @@ verify if hetzner domain needs to be pushed, theres a change on hetzner and some domains need to be migrated +### redirect or page not found + +subdomains or pages that dont exist should have page not found or should redirect + ### docker credential helper WARNING! Your credentials are stored unencrypted in '/home/languagedev/.docker/config.json'. @@ -24,15 +28,6 @@ laptop: verify if docker containers run on startup (they shouldnt) ### vps setup - monitoring and logging (eg via chrootkit or rkhunter, logwatch/monit => mails daily with summary) -- keep the vps clean (e.g. old docker images/containers) - -### cd/ci pipeline - -forgejo actions? smth else? where docker registry, also forgejo? - -### postgres backups - -how? ### try now option diff --git a/documentation/roadmap.md b/documentation/roadmap.md index 825cbc9..7c4b4ed 100644 --- a/documentation/roadmap.md +++ b/documentation/roadmap.md @@ -91,7 +91,7 @@ Each phase produces a working increment. Nothing is built speculatively. --- -## Phase 3 — Auth +## Phase 3 — Auth ✅ **Goal:** Users can log in via Google or GitHub and stay logged in. **Done when:** Better Auth session is validated on protected routes; unauthenticated users are redirected to login; user row is created on first social login. @@ -109,6 +109,68 @@ Each phase produces a working increment. Nothing is built speculatively. --- +## Phase 6 — Production Deployment ✅ + +**Goal:** App is live on Hetzner, accessible via HTTPS on all subdomains. +**Done when:** `https://lilastudy.com` loads; `https://api.lilastudy.com` responds; auth flow works end-to-end; CI/CD deploys on push to main. + +_Note: Deployment was moved ahead of multiplayer — the app is useful without multiplayer but not without deployment._ + +### Infrastructure + +- [x] Hetzner VPS provisioned (Debian 13, ARM64, 4GB RAM) +- [x] SSH hardening, ufw firewall, fail2ban +- [x] Docker + Docker Compose installed +- [x] Domain DNS: A record + wildcard `*.lilastudy.com` pointing to VPS + +### Reverse proxy + +- [x] Caddy container with automatic HTTPS (Let's Encrypt) +- [x] Subdomain routing: `lilastudy.com` → web, `api.lilastudy.com` → API, `git.lilastudy.com` → Forgejo + +### Docker stack + +- [x] Production `docker-compose.yml` with all services on shared network +- [x] No ports exposed on internal services — only Caddy (80/443) and Forgejo SSH (2222) +- [x] Production Dockerfile stages for API (runner) and frontend (nginx:alpine) +- [x] Monorepo package exports fixed for production (dist/src paths) +- [x] Production `.env` with env-driven CORS, auth URLs, cookie domain + +### Git server + container registry + +- [x] Forgejo running with built-in container registry +- [x] SSH on port 2222, dev laptop `~/.ssh/config` configured +- [x] Repository created, code pushed + +### CI/CD + +- [x] Forgejo Actions enabled +- [x] Forgejo Runner container on VPS with Docker socket access +- [x] `.forgejo/workflows/deploy.yml` — build, push, deploy via SSH on push to main +- [x] Registry and SSH secrets configured in Forgejo + +### Database + +- [x] Initial seed via pg_dump from dev laptop +- [x] Seeding script is idempotent (onConflictDoNothing) for future data additions +- [x] Schema migrations via Drizzle (migrate first, deploy second) + +### OAuth + +- [x] Google and GitHub OAuth redirect URIs configured for production +- [x] Cross-subdomain cookies via COOKIE_DOMAIN=.lilastudy.com + +### Backups + +- [x] Daily cron job (3 AM) with pg_dump, 7-day retention +- [x] Dev laptop auto-syncs backups on login via rsync + +### Documentation + +- [x] `deployment.md` covering full infrastructure setup + +--- + ## Phase 4 — Multiplayer Lobby **Goal:** Players can create and join rooms; the host sees all joined players in real time. @@ -148,32 +210,21 @@ Each phase produces a working increment. Nothing is built speculatively. --- -## Phase 6 — Production Deployment - -**Goal:** App is live on Hetzner, accessible via HTTPS on all subdomains. -**Done when:** `https://app.yourdomain.com` loads; `wss://api.yourdomain.com` connects; auth flow works end-to-end. - -- [ ] `docker-compose.prod.yml`: all services + `nginx-proxy` + `acme-companion` -- [ ] Nginx config per container: `VIRTUAL_HOST` + `LETSENCRYPT_HOST` -- [ ] Production `.env` files on VPS -- [ ] Drizzle migration runs on `api` container start -- [ ] Seed production DB -- [ ] Smoke test: login → solo game → multiplayer game end-to-end - ---- - ## Phase 7 — Polish & Hardening **Goal:** Production-ready for real users. +- [x] CI/CD pipeline (Forgejo Actions → SSH deploy) +- [x] Database backups (cron → dev laptop sync) - [ ] Rate limiting on API endpoints - [ ] Graceful WS reconnect with exponential back-off - [ ] React error boundaries - [ ] `GET /users/me/stats` endpoint + profile page - [ ] Accessibility pass (keyboard nav, ARIA on quiz buttons) - [ ] Favicon, page titles, Open Graph meta -- [ ] CI/CD pipeline (GitHub Actions → SSH deploy) -- [ ] Database backups (cron → Hetzner Object Storage) +- [ ] Offsite backup storage (Hetzner Object Storage) +- [ ] Monitoring/logging (uptime, centralized logs) +- [ ] Valkey for game session store (replace in-memory) --- @@ -183,9 +234,9 @@ Each phase produces a working increment. Nothing is built speculatively. Phase 0 (Foundation) ✅ └── Phase 1 (Vocabulary Data + API) ✅ └── Phase 2 (Singleplayer UI) ✅ - └── Phase 3 (Auth) - ├── Phase 4 (Multiplayer Lobby) - │ └── Phase 5 (Multiplayer Game) - │ └── Phase 6 (Deployment) - └── Phase 7 (Hardening) + ├── Phase 3 (Auth) ✅ + │ └── Phase 6 (Deployment + CI/CD) ✅ + └── Phase 4 (Multiplayer Lobby) + └── Phase 5 (Multiplayer Game) + └── Phase 7 (Hardening) ``` diff --git a/documentation/spec.md b/documentation/spec.md index 8539dac..4bf2835 100644 --- a/documentation/spec.md +++ b/documentation/spec.md @@ -63,9 +63,9 @@ These are not deleted from the plan — they are deferred. The architecture is a ## 4. Technology Stack -The monorepo structure and tooling are already set up. This is the full stack — the MVP uses a subset of it. +The monorepo structure and tooling are already set up. This is the full stack. -| Layer | Technology | MVP? | +| Layer | Technology | Status | | ------------ | ------------------------------ | ----------- | | Monorepo | pnpm workspaces | ✅ | | Frontend | React 18, Vite, TypeScript | ✅ | @@ -77,10 +77,11 @@ The monorepo structure and tooling are already set up. This is the full stack | Database | PostgreSQL + Drizzle ORM | ✅ | | Validation | Zod (shared schemas) | ✅ | | Testing | Vitest, supertest | ✅ | -| Auth | Better Auth (Google + GitHub) | ❌ post-MVP | +| Auth | Better Auth (Google + GitHub) | ✅ | +| Deployment | Docker Compose, Caddy, Hetzner | ✅ | +| CI/CD | Forgejo Actions | ✅ | | Realtime | WebSockets (`ws` library) | ❌ post-MVP | | Cache | Valkey | ❌ post-MVP | -| Deployment | Docker Compose, Hetzner, Nginx | ❌ post-MVP | --- @@ -88,14 +89,20 @@ The monorepo structure and tooling are already set up. This is the full stack ```text vocab-trainer/ +├── .forgejo/ +│ └── workflows/ +│ └── deploy.yml — CI/CD pipeline (build, push, deploy) ├── apps/ │ ├── api/ │ │ └── src/ -│ │ ├── app.ts — createApp() factory, express.json(), error middleware +│ │ ├── app.ts — createApp() factory, CORS, auth handler, error middleware │ │ ├── server.ts — starts server on PORT │ │ ├── errors/ │ │ │ └── AppError.ts — AppError, ValidationError, NotFoundError +│ │ ├── lib/ +│ │ │ └── auth.ts — Better Auth config (Google + GitHub providers) │ │ ├── middleware/ +│ │ │ ├── authMiddleware.ts — session validation for protected routes │ │ │ └── errorHandler.ts — central error middleware │ │ ├── routes/ │ │ │ ├── apiRouter.ts — mounts /health and /game routers @@ -111,10 +118,17 @@ vocab-trainer/ │ │ ├── InMemoryGameSessionStore.ts │ │ └── index.ts │ └── web/ +│ ├── Dockerfile — multi-stage: dev + production (nginx:alpine) +│ ├── nginx.conf — SPA fallback routing │ └── src/ │ ├── routes/ │ │ ├── index.tsx — landing page -│ │ └── play.tsx — the quiz +│ │ ├── play.tsx — the quiz +│ │ ├── login.tsx — Google + GitHub login buttons +│ │ ├── about.tsx +│ │ └── __root.tsx +│ ├── lib/ +│ │ └── auth-client.ts — Better Auth React client │ ├── components/ │ │ └── game/ │ │ ├── GameSetup.tsx — settings UI @@ -131,7 +145,7 @@ vocab-trainer/ │ └── db/ │ ├── drizzle/ — migration SQL files │ └── src/ -│ ├── db/schema.ts — Drizzle schema +│ ├── db/schema.ts — Drizzle schema (terms, translations, auth tables) │ ├── models/termModel.ts — getGameTerms(), getDistractors() │ ├── seeding-datafiles.ts — seeds terms + translations from JSON │ ├── seeding-cefr-levels.ts — enriches translations with CEFR data @@ -139,7 +153,9 @@ vocab-trainer/ │ └── index.ts ├── scripts/ — Python extraction/comparison/merge scripts ├── documentation/ — project docs -├── docker-compose.yml +├── docker-compose.yml — local dev stack +├── docker-compose.prod.yml — production config reference +├── Caddyfile — reverse proxy routing └── pnpm-workspace.yaml ``` @@ -178,13 +194,28 @@ HTTP Request **Key principle:** all database code lives in `packages/db`. `apps/api` never imports `drizzle-orm` for queries — it only calls functions exported from `packages/db`. +### Production Infrastructure + +```text +Internet → Caddy (HTTPS termination) + ├── lilastudy.com → web container (nginx, static files) + ├── api.lilastudy.com → api container (Express, port 3000) + └── git.lilastudy.com → forgejo container (git + registry, port 3000) + +SSH (port 2222) → forgejo container (git push/pull) +``` + +All containers communicate over an internal Docker network. Only Caddy (80/443) and Forgejo SSH (2222) are exposed to the internet. + --- ## 7. Data Model (Current State) Words are modelled as language-neutral concepts (terms) separate from learning curricula (decks). Adding a new language pair requires no schema changes — only new rows in `translations`, `decks`. -**Core tables:** `terms`, `translations`, `term_glosses`, `decks`, `deck_terms`, `categories`, `term_categories` +**Core tables:** `terms`, `translations`, `term_glosses`, `decks`, `deck_terms`, `topics`, `term_topics` + +**Auth tables (managed by Better Auth):** `user`, `session`, `account`, `verification` Key columns on `terms`: `id` (uuid), `pos` (CHECK-constrained), `source`, `source_id` (unique pair for idempotent imports) @@ -201,9 +232,10 @@ Full schema is in `packages/db/src/db/schema.ts`. ### Endpoints ```text -POST /api/v1/game/start GameRequest → GameSession -POST /api/v1/game/answer AnswerSubmission → AnswerResult -GET /api/v1/health Health check +POST /api/v1/game/start GameRequest → GameSession (requires auth) +POST /api/v1/game/answer AnswerSubmission → AnswerResult (requires auth) +GET /api/v1/health Health check (public) +ALL /api/auth/* Better Auth handlers (public) ``` ### Schemas (packages/shared) @@ -235,7 +267,7 @@ Typed error classes (`AppError` base, `ValidationError` 400, `NotFoundError` 404 - **Session length**: 3 or 10 questions (configurable) - **Scoring**: +1 per correct answer (no speed bonus for MVP) - **Timer**: none in singleplayer MVP -- **No auth required**: anonymous users +- **Auth required**: users must log in via Google or GitHub - **Submit-before-send**: user selects, then confirms (prevents misclicks) --- @@ -258,14 +290,15 @@ After completing a task: share the code, ask what to refactor and why. The LLM s ## 11. Post-MVP Ladder -| Phase | What it adds | -| ----------------- | -------------------------------------------------------------- | ----------------------------------------------------------------------- | -| Auth | Auth | Better Auth (Google + GitHub), embedded in Express API, 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 | +| Phase | What it adds | Status | +| ----------------- | ------------------------------------------------------------------------------- | ------ | +| Auth | Better Auth (Google + GitHub), embedded in Express API, user rows in DB | ✅ | +| Deployment | Docker Compose, Caddy, Forgejo, CI/CD, Hetzner VPS | ✅ | +| Hardening (partial) | CI/CD pipeline, DB backups | ✅ | +| 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 | ❌ | +| Hardening (rest) | Rate limiting, error boundaries, monitoring, accessibility | ❌ | ### Future Data Model Extensions (deferred, additive) @@ -285,11 +318,16 @@ All are new tables referencing existing `terms` rows via FK. No existing schema - Game mechanic: simultaneous answers, 15-second server timer, all players see same question - Valkey for ephemeral room state, PostgreSQL for durable records -### Infrastructure (deferred) +### Infrastructure (current) -- `app.yourdomain.com` → React frontend -- `api.yourdomain.com` → Express API + WebSocket + Better Auth -- Docker Compose with `nginx-proxy` + `acme-companion` for automatic SSL +- `lilastudy.com` → React frontend (nginx serving static files) +- `api.lilastudy.com` → Express API + Better Auth +- `git.lilastudy.com` → Forgejo (git server + container registry) +- Docker Compose with Caddy for automatic HTTPS via Let's Encrypt +- CI/CD via Forgejo Actions (build on push to main, deploy via SSH) +- Daily DB backups with cron, synced to dev laptop + +See `deployment.md` for full infrastructure documentation. --- @@ -312,14 +350,14 @@ See `roadmap.md` for the full roadmap with task-level checkboxes. ### Dependency Graph ```text -Phase 0 (Foundation) -└── Phase 1 (Vocabulary Data + API) - └── Phase 2 (Singleplayer UI) - └── Phase 3 (Auth) - ├── Phase 4 (Room Lobby) - │ └── Phase 5 (Multiplayer Game) - │ └── Phase 6 (Deployment) - └── Phase 7 (Hardening) +Phase 0 (Foundation) ✅ +└── Phase 1 (Vocabulary Data + API) ✅ + └── Phase 2 (Singleplayer UI) ✅ + ├── Phase 3 (Auth) ✅ + │ └── Phase 6 (Deployment + CI/CD) ✅ + └── Phase 4 (Multiplayer Lobby) + └── Phase 5 (Multiplayer Game) + └── Phase 7 (Hardening) ``` --- From fe0315938a07c9ac0dcdb787281d887dff05f3cc Mon Sep 17 00:00:00 2001 From: lila Date: Wed, 15 Apr 2026 11:56:46 +0200 Subject: [PATCH 7/8] adding documentation for game modes --- documentation/game_modes.md | 83 +++++++++++++++++++++++++++++++++++++ 1 file changed, 83 insertions(+) create mode 100644 documentation/game_modes.md diff --git a/documentation/game_modes.md b/documentation/game_modes.md new file mode 100644 index 0000000..22eff3d --- /dev/null +++ b/documentation/game_modes.md @@ -0,0 +1,83 @@ +# Game Modes + +This document describes the planned game modes for lila. Each mode uses the same lobby system and vocabulary data but differs in how answers are submitted, scored, and how a winner is determined. + +The first multiplayer mode to implement is TBD. The lobby infrastructure (create, join, WebSocket connection) is mode-agnostic — adding a new mode means adding new game logic, not changing the lobby. + +--- + +## TV Quiz Show + +**Type:** Multiplayer +**Answer model:** Buzzer — first to press gets to answer +**Rounds:** Fixed (e.g. 10) + +A question appears for all players. The first player to buzz in gets to answer. If correct, they score a point. If wrong, other players may get a chance to answer (TBD: whether the question passes to the next buzzer or the round ends). The host or a timer controls the pace. + +Key difference from other modes: only one player answers per question. Speed of reaction matters as much as knowledge. + +--- + +## Race to the Top + +**Type:** Multiplayer +**Answer model:** Simultaneous — all players answer independently +**Rounds:** None — play until target score reached + +All players see the same question and answer independently. No fixed round count. The first player to reach a target number of correct answers wins (e.g. 20). Fast-paced and competitive. + +Open questions: what happens if two players hit the target on the same question? Tiebreaker by speed? Shared win? + +--- + +## Chain Link + +**Type:** Multiplayer +**Answer model:** Turn-based — one player at a time, in rotation +**Rounds:** None — play until a player fails + +Players answer in a fixed rotation: Player 1, Player 2, Player 3, then back to Player 1. Each player gets one question per turn. The game continues until a player answers incorrectly — that player is out (or the game ends). Last correct answerer wins, or the game simply ends on the first wrong answer. + +Key difference from other modes: turn-based, not simultaneous. Pressure builds as you wait for your turn. + +Open questions: does the player who answers wrong lose, or does the game just end? If the game continues, does it become elimination? + +--- + +## Elimination Round + +**Type:** Multiplayer +**Answer model:** Simultaneous — all players answer independently +**Rounds:** Continue until one player remains + +All players see the same question and answer simultaneously. Players who answer incorrectly are eliminated. Rounds continue until only one player is left standing. + +Open questions: what if everyone gets it wrong in the same round? Reset that round? Eliminate nobody? What if it comes down to two players and both get it wrong repeatedly? + +--- + +## Cooperative Challenge + +**Type:** Multiplayer +**Answer model:** TBD +**Rounds:** TBD + +Players work together rather than competing. Concept not yet defined. Possible ideas: shared team score with a target, each player contributes answers to a collective pool, or players take turns and the team survives as long as the chain doesn't break. + +--- + +## Single Player Extended + +**Type:** Singleplayer +**Answer model:** TBD +**Rounds:** TBD + +An expanded version of the current singleplayer quiz. Concept not yet defined. Possible ideas: longer sessions with increasing difficulty, mixed POS/language rounds, streak bonuses, progress tracking across sessions, or timed challenge mode. + +--- + +## Schema Impact + +The `lobbies` table includes a `game_mode` column (varchar) with values like `tv_quiz`, `race_to_top`, `chain_link`, `elimination`. Mode-specific settings (e.g. target score for Race to the Top) can be stored in a `settings` jsonb column if needed. + +The singleplayer modes (Single Player Extended) don't require a lobby — they extend the existing singleplayer flow. From a7be7152cc4ae30367a1c65ee677491cc07cb91d Mon Sep 17 00:00:00 2001 From: lila Date: Thu, 16 Apr 2026 14:43:59 +0200 Subject: [PATCH 8/8] adding script to programmatically add issues to the forgejo project kanban --- scripts/create-issues.sh | 280 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 280 insertions(+) create mode 100644 scripts/create-issues.sh diff --git a/scripts/create-issues.sh b/scripts/create-issues.sh new file mode 100644 index 0000000..fefb072 --- /dev/null +++ b/scripts/create-issues.sh @@ -0,0 +1,280 @@ +#!/bin/bash + +# Forgejo batch issue creator for lila +# Usage: FORGEJO_TOKEN=your_token ./create-issues.sh + +FORGEJO_URL="https://git.lilastudy.com" +OWNER="forgejo-lila" +REPO="lila" +TOKEN="${FORGEJO_TOKEN:?Set FORGEJO_TOKEN environment variable}" + +API="${FORGEJO_URL}/api/v1/repos/${OWNER}/${REPO}" + +# Helper: create a label (ignores if already exists) +create_label() { + local name="$1" color="$2" description="$3" + curl -s -X POST "${API}/labels" \ + -H "Authorization: token ${TOKEN}" \ + -H "Content-Type: application/json" \ + -d "{\"name\":\"${name}\",\"color\":\"${color}\",\"description\":\"${description}\"}" > /dev/null + echo "Label: ${name}" +} + +# Helper: create an issue with labels +create_issue() { + local title="$1" body="$2" + shift 2 + local labels="$*" + + # Build labels JSON array + local label_ids="" + for label in $labels; do + local id + id=$(curl -s "${API}/labels" \ + -H "Authorization: token ${TOKEN}" | \ + python3 -c "import sys,json; [print(l['id']) for l in json.load(sys.stdin) if l['name']=='${label}']") + if [ -n "$label_ids" ]; then + label_ids="${label_ids},${id}" + else + label_ids="${id}" + fi + done + + curl -s -X POST "${API}/issues" \ + -H "Authorization: token ${TOKEN}" \ + -H "Content-Type: application/json" \ + -d "{\"title\":$(echo "$title" | python3 -c 'import sys,json; print(json.dumps(sys.stdin.read().strip()))'),\"body\":$(echo "$body" | python3 -c 'import sys,json; print(json.dumps(sys.stdin.read().strip()))'),\"labels\":[${label_ids}]}" > /dev/null + + echo "Issue: ${title}" +} + +echo "=== Creating labels ===" +create_label "feature" "#0075ca" "New user-facing functionality" +create_label "infra" "#e4e669" "Infrastructure, deployment, DevOps" +create_label "debt" "#d876e3" "Technical cleanup, refactoring" +create_label "security" "#b60205" "Security improvements" +create_label "ux" "#1d76db" "User experience, accessibility, polish" +create_label "multiplayer" "#0e8a16" "Multiplayer lobby and game features" + +echo "" +echo "=== Creating issues ===" + +# ── feature ── + +create_issue \ + "Add guest/try-now option — play without account" \ + "Allow users to play a quiz without signing in so they can see what the app offers before creating an account. Make auth middleware optional on game routes, add a 'Try without account' button on the login/landing page." \ + feature + +create_issue \ + "Add Apple login provider" \ + "Add Apple as a social login option via Better Auth. Requires Apple Developer account and Sign in with Apple configuration." \ + feature + +create_issue \ + "Add email+password login" \ + "Add traditional email and password authentication as an alternative to social login. Configure via Better Auth." \ + feature + +create_issue \ + "User stats endpoint + profile page" \ + "Add GET /users/me/stats endpoint returning games played, score history, etc. Build a frontend profile page displaying the stats." \ + feature + +# ── infra ── + +create_issue \ + "Google OAuth app verification and publishing" \ + "Currently only test users can log in via Google. Publish the OAuth consent screen so any Google user can sign in. Requires branding verification through Google Cloud Console." \ + infra + +create_issue \ + "Set up Docker credential helper on dev laptop" \ + "Docker credentials are stored unencrypted in ~/.docker/config.json. Set up a credential helper to store them securely. See https://docs.docker.com/go/credential-store/" \ + infra + +create_issue \ + "VPS monitoring and logging" \ + "Set up monitoring and centralized logging on the VPS. Options: chkrootkit/rkhunter for security, logwatch/monit for daily summaries, uptime monitoring for service health." \ + infra + +create_issue \ + "Move to offsite backup storage" \ + "Currently database backups live on the same VPS. Add offsite copies to Hetzner Object Storage or similar S3-compatible service to protect against VPS failure." \ + infra + +create_issue \ + "Replace in-memory game session store with Valkey" \ + "Add Valkey container to the production Docker stack. Implement ValkeyGameSessionStore using the existing GameSessionStore interface. Required before multiplayer." \ + infra + +create_issue \ + "Modern env management approach" \ + "Evaluate replacing .env files with a more robust approach (e.g. dotenvx, infisical, or similar). Current setup works but .env files are error-prone and not versioned." \ + infra + +create_issue \ + "Pin dependencies in package.json files" \ + "Pin all dependency versions in package.json files to exact versions to prevent unexpected updates from breaking builds." \ + infra + +# ── debt ── + +create_issue \ + "Rethink organization of datafiles and wordlists" \ + "The current layout of data-sources/, scripts/datafiles/, scripts/data-sources/, and packages/db/src/data/ is confusing with overlapping content. Consolidate into a clear structure." \ + debt + +create_issue \ + "Resolve eslint peer dependency warning" \ + "eslint-plugin-react-hooks 7.0.1 expects eslint ^3.0.0-^9.0.0 but found 10.0.3. Resolve the peer dependency mismatch." \ + debt + +# ── security ── + +create_issue \ + "Rate limiting on API endpoints" \ + "Add rate limiting to prevent abuse. At minimum: auth endpoints (brute force prevention), game endpoints (spam prevention). Consider express-rate-limit or similar." \ + security + +# ── ux ── + +create_issue \ + "404/redirect handling for unknown routes and subdomains" \ + "Unknown routes return raw errors. Add a catch-all route on the frontend for client-side 404s. Consider Caddy fallback for unrecognized subdomains." \ + ux + +create_issue \ + "React error boundaries" \ + "Add error boundaries to catch and display runtime errors gracefully instead of crashing the entire app." \ + ux + +create_issue \ + "Accessibility pass" \ + "Keyboard navigation for quiz buttons, ARIA labels on interactive elements, focus management during quiz flow." \ + ux + +create_issue \ + "Favicon, page titles, Open Graph meta" \ + "Add favicon, set proper page titles per route, add Open Graph meta tags for link previews when sharing." \ + ux + +# ── multiplayer ── + +create_issue \ + "Drizzle schema: lobbies, lobby_players + migration" \ + "Create lobbies table (id, code, host_user_id, status, is_private, game_mode, settings, created_at) and lobby_players table (lobby_id, user_id, score, joined_at). Run migration. See game-modes.md for game_mode values." \ + multiplayer + +create_issue \ + "REST endpoints: POST /lobbies, POST /lobbies/:code/join" \ + "Create lobby (generates short code, sets host) and join lobby (validates code, adds player, enforces max limit)." \ + multiplayer + +create_issue \ + "LobbyService: create lobby, join lobby, enforce player limit" \ + "Service layer for lobby management. Generate human-readable codes, validate join requests, track lobby state. Public lobbies are browsable, private lobbies require code." \ + multiplayer + +create_issue \ + "WebSocket server: attach ws upgrade to Express" \ + "Attach ws library upgrade handler to the existing Express HTTP server. Handle connection lifecycle." \ + multiplayer + +create_issue \ + "WS auth middleware: validate session on upgrade" \ + "Validate Better Auth session on WebSocket upgrade request. Reject unauthenticated connections." \ + multiplayer + +create_issue \ + "WS message router: dispatch by type" \ + "Route incoming WebSocket messages by their type field to the appropriate handler. Use Zod discriminated union for type safety." \ + multiplayer + +create_issue \ + "Lobby join/leave handlers + broadcast lobby state" \ + "Handle lobby:join and lobby:leave WebSocket events. Broadcast updated player list to all connected players in the lobby." \ + multiplayer + +create_issue \ + "Lobby state in Valkey (ephemeral) + PostgreSQL (durable)" \ + "Store live lobby state (connected players, current question, timer) in Valkey. Store durable records (who played, final scores) in PostgreSQL." \ + multiplayer + +create_issue \ + "WS event Zod schemas in packages/shared" \ + "Define all WebSocket message types as Zod discriminated unions in packages/shared. Covers lobby events (join, leave, start) and game events (question, answer, result, finished)." \ + multiplayer + +create_issue \ + "Frontend: lobby browser + create/join lobby" \ + "Lobby list showing public open lobbies. Create lobby form (game mode, public/private). Join-by-code input for private lobbies." \ + multiplayer + +create_issue \ + "Frontend: lobby view (player list, code, start game)" \ + "Show lobby code, connected players, game mode. Host sees Start Game button. Players see waiting state. Real-time updates via WebSocket." \ + multiplayer + +create_issue \ + "Frontend: WS client singleton with reconnect" \ + "WebSocket client that maintains a single connection, handles reconnection on disconnect, and dispatches incoming messages to the appropriate state handlers." \ + multiplayer + +create_issue \ + "GameService: question sequence + server timer" \ + "Generate question sequence for a lobby game. Enforce per-question timer (e.g. 15s). Timer logic varies by game mode — see game-modes.md." \ + multiplayer + +create_issue \ + "lobby:start WS handler — broadcast first question" \ + "When host starts the game, generate questions, change lobby status to in_progress, broadcast first question to all players." \ + multiplayer + +create_issue \ + "game:answer WS handler — collect answers" \ + "Receive player answers via WebSocket. Track who has answered. Behavior varies by game mode (simultaneous vs turn-based vs buzzer)." \ + multiplayer + +create_issue \ + "Answer evaluation + broadcast results" \ + "On all-answered or timeout: evaluate answers, calculate scores, broadcast game:answer_result to all players. Then send next question or end game." \ + multiplayer + +create_issue \ + "Game finished: broadcast results, update DB" \ + "After final round: broadcast game:finished with final scores and winner. Write game results to PostgreSQL (transactional). Change lobby status to finished." \ + multiplayer + +create_issue \ + "Frontend: multiplayer game route" \ + "Route for active multiplayer games. Receives questions and results via WebSocket. Reuses QuestionCard and OptionButton components." \ + multiplayer + +create_issue \ + "Frontend: countdown timer component" \ + "Visual countdown timer synchronized with server timer. Shows remaining seconds per question." \ + multiplayer + +create_issue \ + "Frontend: ScoreBoard component (live per-player scores)" \ + "Displays live scores for all players during a multiplayer game. Updates in real-time via WebSocket." \ + multiplayer + +create_issue \ + "Frontend: GameFinished screen" \ + "Winner highlight, final scores, play again option. Returns to lobby on play again." \ + multiplayer + +create_issue \ + "Multiplayer GameService unit tests" \ + "Unit tests for round evaluation, scoring, tie-breaking, timeout handling across different game modes." \ + multiplayer + +create_issue \ + "Graceful WS reconnect with exponential back-off" \ + "Handle WebSocket disconnections gracefully. Reconnect with exponential back-off. Restore game state on reconnection if game is still in progress." \ + multiplayer + +echo "" +echo "=== Done ==="