Skip to content

Reading Paths

Francisca Portugal edited this page Oct 27, 2026 · 1 revision

Reading paths

Pick the path that matches what you want to do. Each one is ordered, and you can stop as soon as you have what you need.

Only here to use TTS? Open the planner or the FAQ. You do not need any of this.

Legend: 🚧 means the dedicated wiki page is not written yet; a temporary link to the code or an existing repo doc is given instead.


Newcomer — first week

Goal: run the project locally and land a first pull request. Allow about half a day.

  1. What is TTS — the problem and the shape of the system.
  2. Quick start — clone, database, seed, run both servers.
  3. CONTRIBUTING.md — branch from the milestone branch, never PR main, commits, PR size, code standards.
  4. Glossary — course vs course unit vs occurrence vs class. Read it before your first issue or review; it prevents most misunderstandings.
  5. Architecture overview 🚧 — for now, the project map and the layer summary under it.
  6. Pick a good first issue.

Issues are assigned by the project manager. Comment on the issue or ask in the team channel — do not self-assign.


Backend

Goal: ship or change an endpoint. Start with a T1 (read-only) issue.

  1. Glossary — the entities you will query.
  2. API design doc — what each endpoint does, its auth, and its request/response shapes. The status-checked catalog is 🚧.
  3. Tech stack — why Bun, Elysia, Prisma 8, and how the client is used.
  4. Backend layers 🚧 — the dependency rule and where new code belongs. Until it is written, read the comments at the top of apps/backend/src/interface/routes/courses.routes.ts.
  5. Request lifecycle 🚧 — middleware → route → use-case → domain → repository → error handler.
  6. Database guide — the Prisma 8 contract, migrations, backfills and recovery.
  7. Error handling 🚧 — HttpError, stable error codes, 400 vs 422. Until then, read apps/backend/src/interface/errors/ and middleware/error-handler.ts.
  8. Testing 🚧 — bun:test, fake repositories, createApp().handle(request). Until then, read apps/backend/tests/interface/routes/ and its support/ helpers.
  9. Adding an endpoint 🚧 — the full checklist.

Interim shortcut: read one route file end to end (courses.routes.ts) together with its test (tests/interface/routes/catalog/courses.test.ts). That pair is the reference implementation.


Frontend

Goal: change the planner or a page.

  1. Glossary — especially option, course option, picked course, occurrence.
  2. Frontend source — browse pages/, components/, contexts/, hooks/, api/.
  3. Directory tour 🚧 — what lives where. Interim: the old wiki's File-Structure is stale; do not follow it.
  4. State & contexts 🚧 — the context map and the localStorage / backend split.
  5. Data fetching 🚧 — SWR + Eden Treaty, caching and errors.
  6. Planner 🚧 — options, conflicts, locks, teacher filters.
  7. Exchange 🚧 — the exchange flow end to end.
  8. Styling 🚧 — Tailwind v4, cn(), Radix/Headless UI.

Interim shortcut: contexts/CombinedProvider.tsx lists every provider; components/planner/ contains the planner itself.


Operations / infrastructure

Goal: deploy, debug or change CI.

  1. README — environment variables and Docker.
  2. Environments 🚧 — local, dev, staging, production and their URLs.
  3. CI workflows — typecheck, tests, lint, sigarra SDK drift, deploy.
  4. Deployment 🚧 — Docker images, the Niployments /api mount, nginx.
  5. Monitoring 🚧 — Sentry (tunnelled through /feedback), analytics.
  6. Runbooks 🚧 — rollback, database restore, secret rotation.

Interim shortcut: Dockerfile, docker-compose.yaml, apps/backend/.env.schema, apps/frontend/.env.schema and .github/workflows/ together describe the whole deployment.


Reviewer / coordinator

Goal: review a PR or triage an issue.

  1. CONTRIBUTING.md — the rules being enforced.
  2. What is TTS — scope: does the change belong in TTS at all?
  3. API design doc — does the endpoint match the contract, including error codes?
  4. Glossary — are the names right? Reject Major for Course, course_unit_id for occurrenceId, and similar legacy leaks.
  5. PR template.

Where to ask


Last verified: 2026-10-27 · source: docs/wiki/00-orientation/reading-paths.md

Clone this wiki locally