formatting + adding issues

README.md

@@ -30,7 +30,7 @@ Live at [lilastudy.com](https://lilastudy.com).
 
 ## Repository Structure
 
-```
+```tree
 lila/
 ├── apps/
 │   ├── api/        — Express backend
@@ -50,7 +50,7 @@ lila/
 
 Requests flow through a strict layered architecture:
 
-```
+```text
 HTTP Request → Router → Controller → Service → Model → Database
 ```
 
@@ -71,7 +71,7 @@ Vocabulary data is sourced from WordNet and the Open Multilingual Wordnet (OMW).
 
 ## API
 
-```
+```text
 POST /api/v1/game/start     — start a quiz session (auth required)
 POST /api/v1/game/answer    — submit an answer (auth required)
 GET  /api/v1/health         — health check (public)
@@ -90,7 +90,7 @@ Rooms are created via REST, then managed over WebSockets. Messages are typed via
 
 ## Infrastructure
 
-```
+```tree
 Internet → Caddy (HTTPS)
             ├── lilastudy.com      → web (nginx, static files)
             ├── api.lilastudy.com  → api (Express)

documentation/backlog.md

@@ -23,6 +23,12 @@ Things that are actively in progress or should be picked up immediately. Mostly
 
 Clearly planned work, not yet started. No hard ordering — sequence based on what unblocks real users first.
 
+- **Batch distractor queries to eliminate N+1** `[debt]`
+  createGameSession calls getDistractors once per term in parallel — 3 queries for 3 rounds, 10 for 10. Each query does ORDER BY RANDOM() which can't use an index and gets slower as the translations table grows. Fix: add a getDistractorsForTerms(termIds[], ...) function to @lila/db that batches all distractor fetches into a single query and returns results grouped by term. The service distributes the results per question. Prerequisite: none. Blocked by: nothing, but coordinate with any ongoing @lila/db changes.
+
+- **Atomic session creation** `[debt]`
+  createGameSession reads from Postgres (getGameTerms, getDistractors) then writes to the session store (in-memory/Valkey). A crash between the two leaves the terms consumed with no session created — the user gets an error and retries, no data is corrupted, but the work is wasted. A true transaction boundary isn't achievable across two different systems (Postgres + Valkey have no shared coordinator). Options when revisiting: store sessions in Postgres instead of Valkey (full transactionality, higher latency), or accept the current behaviour and add retry logic on the client. Revisit after Valkey is in production and actual failure rates are observable.
+
 - **Guest / try-now flow** `[feature]`
   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 landing/login page.