LairsFlow is a per-question timer and question-logging tool for exam preparation, built for JEE, NEET, and UPSC aspirants, but usable for any syllabus-based exam since chapters and topics are entirely user-defined. This page documents exactly what the app does, how each part works, and why it is built the way it is.
The core problem LairsFlow addresses
Most students preparing for a competitive exam lose marks not because they lack knowledge, but because they lack time-awareness. A student can burn eight minutes on a two-mark question and then rush through ones they knew cold, and never notice this pattern because a generic stopwatch or Pomodoro timer has no opinion on pacing at all. LairsFlow is built specifically to make this pattern visible and fixable.
Core concept: sessions and chapters
A "session" (called a chapter in the interface) is a subject and chapter or topic pairing that a student is currently studying, for example Physics paired with Electrostatics. Chapters are created from the sidebar or the full Chapter Panel ("View all"), and can be added one at a time or bulk-imported from a JSON file, so setting up an entire syllabus takes minutes rather than an evening. A subject is not a separate object in the data model: it exists only by being referenced on at least one chapter, and gets created implicitly the first time a student types a new subject name while adding a chapter.
The per-question timer methodology
This is the entire premise of the app, so it is worth explaining in detail. LairsFlow is not a generic Pomodoro or stopwatch. The workflow is a tight loop:
- Pick a chapter.
- Set a time budget for exactly one question, for example three minutes.
- Attempt that single question against the countdown.
- Log what happened.
- Immediately start the next timer.
A question can end in one of two ways. If the student solves it before time runs out, they tap the timer early, which opens the log screen with "solved within budget" pre-filled. If the timer reaches zero first, that is not treated as a failure or an interruption: it simply means the question took longer than the target, and the student logs the real outcome and moves on.
Every entry records two numbers: timerSetting (the target the student set) and timeOnQuestion (what actually happened). Comparing these two values, per question, per chapter, or in aggregate, is what lets a student (or the Advisor, described below) reason about real pacing instead of guesswork. This is directly useful preparation for exams like JEE, NEET, and UPSC, where per-question time budgets genuinely determine the final score.
While a session is running, a floating element called the Dynamic Island stays visible with the current chapter name, total session time, and time spent on the current question, plus a one-tap stop button. An Undo button on the timer screen removes the last logged question for the active chapter if a mistake was made while logging.
Logging a question
The log screen appears after a timer ends or is stopped early. Its core structure is a single fork: did the student solve the question or not. From there:
- Difficulty is recorded as Easy, Medium, or Hard.
- The resource used is recorded (textbook, coaching notes, video, or a custom resource the student defines).
- If the question was not solved, the outcome is recorded (wrong answer, did not attempt, or similar) along with a mistake type: conceptual, calculation, silly or careless, or time management.
- An optional notes field with quick-note shortcuts allows a short free-text remark.
Separating mistakes into these categories matters because "I keep making silly mistakes" is rarely an actual diagnosis. A conceptual gap needs revision of the underlying idea. A calculation slip needs more timed numerical practice, not more theory. A time-management miss needs pacing work, not content review. Without tagging the mistake type at the moment it happens, these four very different problems blur into one vague complaint that no amount of generic advice can fix.
"Save & Next" logs the question and immediately opens the next timer, with no interruption or context switch. "Skip" discards the log entry and moves on regardless.
Dashboard and analytics
The dashboard (reached from the account menu at the bottom of the sidebar) turns every logged question into a pattern a student can act on, without any separate spreadsheet or manual tracking. It shows KPI cards (total questions, solve rate, average time per question), a filter row to scope by subject, chapter, or date range, a GitHub-style activity heatmap of daily question volume, a day-wise accuracy trend line, and a question-quality breakdown by outcome and mistake type. Most widgets support an Overview versus Today toggle.
Syllabus pacing
A student can set a target exam date once. After that, every relevant stat, including the dashboard and the Advisor's answers, starts weighing "days remaining" against "chapters remaining." This reframes daily planning away from a raw hours-studied number (a number that is easy to hit without genuine progress) and toward the actual question that matters: is the syllabus going to be finished in time at the current pace.
Export and data ownership
Logged data can be exported as JSON at any time, scoped to an entire subject or a single chapter, filtered by date range (all time, seven days, or today). This exists both as a backup mechanism and for students who want to analyze their own data outside the app.
Account and cloud sync
Signing in with Google is optional. Without signing in, everything stays local to the browser via localStorage. Signing in enables Firebase-backed cloud sync across devices for the question log, chapters, and Advisor conversations. The same account menu holds a "Set study goal" entry, opening a profile modal (goal exam, target year, study hours per day, strengths and weaknesses, coaching-style preference). This profile is optional and purely contextual: it calibrates the Advisor's tone and suggestions, and does not change how the rest of the app behaves.
The LairsFlow Advisor
The Advisor is an AI chat assistant that lives on its own page (p/advisor.html), separate from the main app. It requires the student's own Gemini API key (free from Google AI Studio, entered under Advisor settings) and Google sign-in. It is limited to ten prompts per day, tracked per device, and only prompts that receive a successful reply count against that limit.
What makes the Advisor different from a generic chatbot is that every answer is computed from a fresh snapshot of the student's own question log, accuracy, and pacing data, the same underlying numbers the dashboard uses. It is not guessing or giving generic study tips: it is reasoning over the student's actual recorded performance.
A context menu above the chat input lets the student control exactly which data categories are sent with each message (profile, question log summary, reports and pacing, raw data, and, if a phone is paired, phone-companion data). Categories default sensibly: profile and summarized log data are on by default, while raw data and phone-companion data default off since they are either heavier on tokens or more sensitive. If the Advisor genuinely needs a category that is switched off to answer well, it asks the student to enable it rather than guessing or claiming it has no way to know.
Two structured flows are built directly into the Advisor: setting a target in the morning (it proposes a concrete plan based on stale chapters, weak subjects, and the student's pacing goal) and logging the day in the evening (it already knows the actual completion numbers and only asks two to four short questions about what it cannot know, such as how a session felt). The Advisor can also schedule reminders, which fire in-app regardless of any other setup, and additionally as a phone notification if the student has paired an Android device through the optional Phone Companion.
Phone Companion
Phone Companion is an entirely optional Android companion app that syncs screentime, app-usage, device-status, and notification data into LairsFlow via Firestore, so the Advisor can reason about real distraction patterns instead of relying only on self-reported notes. Every category is off by default after pairing, and each one is switched on independently by the student. Recent phone notifications (which can include message previews) is the most sensitive category and is meant to be enabled last, only if the student specifically wants the Advisor reasoning about a distraction that showed up as a notification rather than just an app open.
Frequently asked questions
Do I need my own Gemini API key? Yes. The Advisor does not ship with a shared backend key. A free key is obtained from Google AI Studio and pasted into Advisor settings. Multiple keys can be saved and switched between if one hits its free-tier limit.
How many Advisor prompts do I get per day? Ten per day, tracked per device. Only prompts that get a successful reply count against the limit; a failed call or a Retry that fails does not use one up.
What data can the Advisor see? Only whatever is toggled on in the context menu above the chat input. Profile, question log summary, and reports and pacing are on by default. Raw data and Phone Companion data start off. If the Advisor needs something that is off, it asks before answering rather than guessing.
Is Phone Companion required? No. It is entirely optional, and every individual toggle inside it starts off even after pairing. Pairing itself only tells the Advisor whether a phone is synced; a specific toggle must be turned on before any actual content is visible to it.
Can LairsFlow be used for exams other than JEE, NEET, or UPSC? Yes. Chapters are just subject and topic pairs defined by the student, so the same timer and logging loop works for any syllabus-based exam, competitive or otherwise.
What happens to my Daily Reports if I clear a chat? Nothing. Clearing a chat only wipes that conversation's local chat history. Saved targets and logs in the Reports tab are untouched.
Where is my data stored? If signed in, the question log, Daily Reports, and Advisor chat history sync via Firestore across devices. If not signed in, everything stays local to that device only.
Is LairsFlow free? Yes, the core app, timer, logging, and dashboard are free to use. The Advisor requires the student's own free Gemini API key rather than a paid subscription.