Methodology

Timetable generator: the algorithm, the guarantees, the limits

This is the trust contract behind the timetable generator. The planner runs entirely in your browser — no server, no account, nothing uploaded — using the method below. If a number in your plan can’t be derived from these rules, tell us.

The algorithm, step by step

  1. Horizon. The plan runs from your start date (default: today) through your latest exam date. With no exams entered, it plans a 2-week study block.
  2. Eligible subjects each day. A subject is studied only while it still has an exam on or after that day. A subject whose exams have all passed is done; a subject with no exams studies through the whole plan.
  3. Reviews first. Any spaced-repetition review due today is placed before new study — 20 minutes each, only if the review’s exam date hasn’t passed.
  4. New study by urgency weight. For each eligible subject, weight = priority ÷ max(days left, 0.5), where priority is 1–3. The planner rotates subjects round-robin in weight order (heaviest first, ties broken alphabetically), so no subject starves — an urgent weak subject gets more turns, not the whole day.
  5. Session queueing. New study sessions (25, 50 or 90 minutes, your choice) are placed back-to-back from your chosen day-start time, with your break length between them.
  6. Review scheduling. Each study session queues follow-up reviews at +1, +3, +7 and +14 days — never past the subject’s exam date. A review that lands on a rest day, or that doesn’t fit in a day’s remaining time, is retired, not silently shifted.

Hard guarantees

  • Daily hour cap. Sessions + breaks on a day never exceed your stated daily minutes. The cap is checked before every placement — a day that can’t fit another session simply ends early.
  • Rest days. Days you mark as rest get zero sessions. Reviews due on a rest day are skipped (retired, not moved).
  • Date-only math. All day counts use calendar-date arithmetic in your local timezone — never timestamps — so daylight-saving transitions cannot shift a day or corrupt a review offset.
  • Invalid dates rejected. Non-existent dates (e.g. 2026-02-30), exam dates before the start date, zero available hours, and priorities outside 1–3 are refused with plain-language errors, never silently “fixed”.
  • Deterministic. Same inputs → same plan. Nothing is random; regeneration is reproducible.

Known limits

  • Priority weights are relative, not absolute. A subject with weight 10 gets roughly twice the turns of one with weight 5 — the planner balances, it doesn’t compute an exact hour quota per subject.
  • Reviews are a fixed 20 minutes, not proportional to the session they follow.
  • Overloaded days are flagged, not rebalanced. If your goals don’t fit your hours, the plan tells you — it won’t quietly borrow time from other days.
  • The planner places sessions back-to-back from one day-start time; it does not spread sessions across the day or schedule around existing commitments.

.ics export: UTC, not floating

The exported calendar file uses absolute UTC timestamps (the Z suffix, e.g. DTSTART:20261105T103000Z), converted from your plan’s local times at export. Practically this means:

  • Events appear at the correct local time wherever your calendar is — exporting in Kathmandu and importing on a phone in London still lands the session at the right moment.
  • If your timezone observes daylight saving, a plan exported before a DST change keeps its absolute times — sessions won’t drift relative to the clock shift.
  • The file follows the iCalendar spec: folded lines at 75 octets, escaped special characters in titles/descriptions, one VEVENT per session labeled Study: or Review:, with the exam date in the description.

Share links: what they carry, and the privacy trade-off

  • Encoding. A share link encodes your inputs (subjects, exam dates, daily minutes, session length, breaks, rest days) as versioned JSON (v:1), serialized to base64url and placed in the URL hash. No link ever leaves your device except when you copy and send it.
  • Size guard. The app refuses to build a link longer than 1,500 encoded characters (SHARE_LIMIT) and tells you to trim inputs instead. This keeps links pasteable in chat apps and emails.
  • Version gate. A link opens only if its version tag matches (v:1); anything else — or corrupted data — gets a plain “broken link” error, never a half-loaded plan. Decoded links are re-validated through the real generator before display.
  • PRIVACY NOTE The link contains your full plan inputs in readable-after-decoding form — anyone with the link can see your subjects, exam dates and schedule. Share only with people you trust, and know that anyone who forwards the link forwards your data. There is no way to revoke a link once sent.

Hand-verify any plan

  1. Pick a day: sessions should total at most your daily minutes, starting at your day-start time.
  2. Pick a study session: reviews for it should appear on the +1/+3/+7/+14 day marks, each 20 minutes, on or before the exam.
  3. Rest days should be empty; no sessions should exist for a subject after its last exam.

← Back to methodology overview