Reference

Reference

Lookup tables. Everything here was read off the code rather than remembered — but code moves, so treat a surprise as a reason to check the source, not as a fact.

Environment variables #

Note: .env.example also contains FINANCIAL_MODELLING_PREP_API_KEY. No code reads it — it is a leftover from an SMI data provider that did not work out. Safe to delete.

Public endpoints #

No authentication.

Student endpoints #

Require Authorization: Bearer <jwt>.

Vote submission fails with:

Every one of these endpoints joins votes for the authenticated user only. No student can see another student's vote through the API.

Admin endpoints #

Require Authorization: Bearer <ADMIN_TOKEN>. A wrong or missing token gives 403.

POST /admin/questions body:

{
  "title": "string, 1-200 chars",
  "description": "string, required",
  "option_a": "string, required",
  "option_b": "string, required",
  "image_url": "string, optional",
  "deadline": "ISO-8601 date-time, required"
}

Database tables #

SQLite in WAL mode, foreign keys on.

users — id, pseudonym (unique), email (unique), password_hash (bcrypt), email_notifications, created_at.

password_resets — id, user_id, token_hash (SHA-256 of the emailed token), expires_at, used_at, created_at.

questions — id, title, description, option_a, option_b, image_url, deadline, resolved_at, ground_truth ('A'/'B'/null), created_at, plus option_a_image, option_b_image, option_a_views, option_b_views, published_at, race_starts_at, race_ends_at, notified_at.

votes — id, user_id, question_id, choice ('A'/'B'), is_correct (null until resolved, then 0/1), voted_at. Unique on (user_id, question_id), which is what makes voting one-shot.

smi_questions — id, question_date (unique), question_id, prev_close, prev_date, created_at.

youtube_suggestions — id, suggested_date (unique), per-video *_id, *_title, *_channel, *_thumbnail, *_subscribers, *_published_at, *_views, then approved, question_id, and the race snapshots race_start_views_a/b, race_start_at, race_end_views_a/b, race_end_at.

Schema changes are additive ALTER TABLE statements in apps/backend/src/db/migrate.ts, wrapped in try/catch and re-run on every start. There is no migration versioning — adding a column means appending to that list.

Export CSV columns #

question_id, deadline, pseudonym, question_title, option_a, option_b,
ground_truth, user_vote, is_correct, voted_at

Ordered by deadline, then question_id, then pseudonym. Unresolved questions appear with empty ground_truth and is_correct.

Frontend routes #

Commands #

# Development
docker compose up --build                    # both services, hot reload
docker compose exec backend npm run seed     # test data
docker compose down -v                       # stop and wipe the database

npm run dev                                  # local, without Docker
npm run seed

# Quality
npm run test                                 # all workspaces
npm run test --workspace=apps/backend
npx vitest run apps/backend/src/test/auth.test.ts    # single file
npm run lint
npm run format

# Docs site
cd docs-site && npm install && npm run build
npm run serve                                # preview on :4180
npm run dev                                  # rebuild on save

# Analysis
cd analysis && pip install -r requirements.txt
python test_expert_algorithm.py
python run.py votes.csv --sweep

Source map #

Where to look when the answer is not in this handbook.