This is the first official version of LairsFlow, and it has a name: Vivran v1. This guide explains the whole app from the very beginning, assuming you have never opened it. Read it top to bottom and you will understand every screen, every button, and every number LairsFlow produces. The sections follow the order you would actually meet the app in, from your first visit through to reading your own analytics and talking to the AI Advisor.
If you only want the exhaustive reference, jump to the Feature guide and the UI map near the end.
1. What LairsFlow is, in one paragraph
LairsFlow is a per-question timer and question-logging tool for exam preparation. It is built with JEE, NEET, and UPSC in mind, but it works for any syllabus-based exam because you define your own subjects and chapters. The core idea is simple: instead of studying against a vague stopwatch, you attempt one question at a time against a time budget you set, then record what happened. Over hundreds of questions, that record turns into a precise picture of your speed, accuracy, and coverage, which the dashboard visualises and the AI Advisor reasons over.
2. Why it works this way
Most students lose marks not from lack of knowledge but from lack of time-awareness. You can spend eight minutes on a two-mark question, rush the ones you knew cold, and never notice the pattern, because a generic timer has no opinion about pacing. LairsFlow makes that pattern visible. Every question you log carries the time you actually took versus the time you intended, plus whether you solved it, how hard it was, and why you missed it if you did. That is the raw material for everything else.
3. Getting in: local first, cloud optional
Open the app and you can start immediately as a guest. Nothing forces you to sign in. In guest mode, all your data lives in this one browser on this one device (in its local storage).
Signing in with Google (from the account card at the bottom of the sidebar) turns on cloud sync through Firebase. Your chapters, logged questions, reports, and goal then follow you across devices, and a small sync dot on the account card shows the status. Sign-in is also the gate for the AI Advisor, which needs a signed-in account plus your own free Gemini API key.
The practical rule: you can try the whole timer-and-logging loop as a guest, but sign in before you build up data you care about, so it is backed up in the cloud.
4. Setting up your subjects and chapters
Everything in LairsFlow hangs off a chapter, which is really a subject plus a topic pairing, for example Physics and Electrostatics. You practise against chapters, and every logged question belongs to one.
There are two ways to create them:
- One at a time. In the sidebar, use the three-dot menu next to the Subject dropdown to Add Subject, or open the chapter panel ("View all") and add chapters there. A subject exists simply by being used on at least one chapter; there is no separate subjects list to manage.
- In bulk, by import. The "Upload Chapters" option (in the account menu) takes a subject name and a JSON file listing all the chapter names, and creates them in one go. If you do not have that file, the same screen gives you a ready-made prompt you can copy and paste into any AI, along with your syllabus or a textbook contents page, to produce the exact format it expects. This is the fastest way to load an entire subject's worth of chapters at once.
Once a subject is selected, its chapters appear as quick-access chips in the sidebar. You can star up to three chapters to pin them to the top, and open the full chapter panel to edit, reset, or delete any of them.
5. Your first focus session
The centre of the app is the timer screen. The flow is:
- Pick a subject, then a chapter from the sidebar. Until you do, the timer shows "select a session to begin".
- Set the time budget for one question in the minutes:seconds field below the timer, for example 3:00. This is your target for a single question, not for a whole study block.
- Tap the timer to start. A focus session begins on that chapter.
While the timer runs, a floating "Dynamic Island" appears at the top of the screen showing the chapter name, your total session time, and the time on the current question, with a red button to end the session.
A question can end two ways, and both are normal:
- You solve it before time runs out. Tap the timer to stop it early. That immediately opens the log screen so you can record the question as solved within budget.
- The timer hits zero first. This is not a failure. It just means the question took longer than your target, which is useful information. Log it and move on.
There is also an Undo button on the timer screen to remove the last question you logged for the current chapter, in case you recorded it wrong.
6. Logging a question
After a question ends, the log screen captures what happened before the next timer starts. The loop is designed so you never break stride between questions. The fields are:
- The fork: "Solved it" or "Didn't get it". This is the one decision everything else follows from.
- If you did not get it: a "What happened?" choice of "Time ran out", "Made a mistake", or "Skipped". If you made a mistake, you then pick a mistake type: Silly, Conceptual, Mis-ID, Formula, or Calculation.
- Difficulty: Easy, Medium, or Hard.
- Resource: PYQ, Module, Cengage, or a custom resource you type in (for example "HC Verma Ch 12").
- Question Reference (optional): exactly which question it was, for example "Exercise 6.4 Q12".
- Notes (optional): free text, with quick chips like "Will reattempt", "Understood", "Still confused", and "Careless error".
Then "Save & Next" logs it and starts the next timer, or "Skip" starts the next timer without logging.
The three fields that matter most for your analytics are solved, difficulty, and mistake type. They take two taps each and unlock almost the entire dashboard. The rest is optional detail that the Advisor can use for exact lookups later.
7. Reading the dashboard
Open the Dashboard from the account menu. It turns your log into KPIs, charts, and breakdowns, all of which react to a filter row at the top (scope by subject, then by chapter). Many widgets also have their own Overview versus Today toggle.
At a glance, the dashboard shows: headline KPIs (questions, solve rate, average time, mistakes), session-length stats, a GitHub-style activity heatmap, an activity line, a running accuracy trend, a rolling speed trend, mistake and question-quality breakdowns, a weak-chapters leaderboard, and a syllabus pacing gauge.
Because the exact formula behind each number matters, there is a dedicated companion post that walks through every calculation, including precisely how your "current pace" is defined and what it does and does not account for: Reading the LairsFlow Dashboard. If you want to trust the charts, read that one next.
8. Setting a study goal and syllabus pacing
From the account menu, "Set study goal" opens the profile modal. Most of it is optional context that helps the Advisor calibrate its advice: your goal exam (JEE, NEET, UPSC, or Other), target year, study hours per day, strengths and weak spots, and how you want to be coached.
The same modal is also where syllabus pacing is configured, and this part does change what you see: you give a short goal description and a duration such as "3 months" or "90 days", which the app turns into a deadline. That is what lights up the pacing gauge on the dashboard. Pacing is set here, not through the Advisor. One honest caveat the app itself flags: pacing can only reason about chapters you have actually added, not the full official syllabus, so treat it as a coverage signal rather than a mastery score.
9. The AI Advisor
The Advisor is LairsFlow's coaching layer, and it lives on its own page (reached from the "LairsFlow Advisor" card in the sidebar). Its whole point is that it reasons over your actual logged data, not generic study tips.
To use it you need to be signed in with Google, and you need your own free Gemini API key, which you set once in "Advisor settings". The key is stored only in your browser and sent directly to Google. Usage is capped at ten prompts per day, deliberately, to keep you studying rather than chatting.
The Advisor page has its own sidebar with a "New chat" button, two tabs (Chat and Reports), and a list of past conversations. In the Chat tab you can type freely or use the quick-action chips, "Set today's target" and "Log today's day", which drive two structured daily-report flows. The Reports tab is your history of those daily reports.
Two capabilities worth knowing:
- It can schedule reminders. Describe a plan ("remind me to start at 7pm", or "I have an event tomorrow until 4pm") and it will schedule an in-app reminder, reasoning like a study partner (for example, adding a buffer after a tiring commitment and framing the first session as light). This always works with no setup.
- It can notify your phone too, optionally. If you pair your phone using the bell icon and the companion app's Sync ID, the same reminders also fire as phone notifications. This is a bonus, never a requirement.
There is also a context menu above the chat input that controls exactly which slices of your data are sent with each message, so you can keep prompts lean and only include heavy data (like your full question log) when a question actually needs it.
10. Managing and moving your data
LairsFlow gives you full ownership of your data through several distinct tools in the account menu. It is worth knowing which does what:
- Export Data: exports logged questions as JSON, scoped to a subject or a single chapter and a date range. Best for inspecting or analysing a slice externally.
- Backup All Data: downloads one JSON file with everything (all chapters, every logged question, reports, custom resources, and your profile). This is the lossless, whole-account backup.
- Restore Backup: re-imports a backup file, replacing the data on this device (and overwriting the cloud on next sync if you are signed in). This is how you move to a new device or recover.
- Clear Local Data: wipes only this browser's local copy. For a signed-in user it does not delete anything permanently; the cloud re-syncs on reload. Use it to fix a stale-data glitch.
- Wipe Everything (cloud too): the irreversible option that deletes your study data from the cloud as well as locally, so it actually sticks. It leaves AI chat history and any paired phone alone.
If you are signed in and data seems to "come back" after clearing, that is because Clear Local Data is local-only by design; Wipe Everything is the one that removes it everywhere.
11. What is new and polished in Vivran v1
Vivran v1 is the first version we are calling official. Alongside the core timer, logging, dashboard, and Advisor, this version brings:
- A redesigned dashboard with session-length stats, a weak-chapter leaderboard, a rolling speed trend, and the syllabus pacing gauge.
- Lossless whole-account Backup and Restore, plus a true "Wipe Everything" that clears the cloud, not just the local copy.
- A consistent custom dropdown control across the whole app, replacing the browser's default dropdowns so subject and chapter pickers look and behave the same everywhere.
- Accurate, honest pacing that reports coverage breadth and openly flags its limits, so it never pretends a shallow pass is mastery.
12. Feature guide
A feature-by-feature reference. Each entry says what it does and where to find it.
Per-question timer. Set a time budget for a single question and attempt it against the clock. Timer screen (home). Requires a selected subject and chapter.
Dynamic Island. Live status while a session runs: chapter name, total session time, current question time, and a stop button. Appears at the top of the screen during a session.
Question logging. Capture solved/unsolved, what happened, mistake type, difficulty, resource, a question reference, and notes, per question. Log screen, shown after each question.
Undo last question. Remove the most recently logged question for the current chapter. Undo button on the timer screen.
Subjects and chapters. Create, edit, star (up to three pinned), reset, and delete. Sidebar subject dropdown, the three-dot menu, and the "View all" chapter panel.
Upload Chapters (bulk import). Create many chapters at once from a JSON list, with a built-in copyable prompt to generate that JSON from your syllabus. Account menu.
Wipe Stats / Reset Log. Delete the logged questions for a whole subject, or for a single chapter, while keeping the subject and chapters themselves. Subject three-dot menu (Wipe Stats) and each chapter's menu (Reset Log).
Dashboard. KPIs, session-length stats, activity heatmap, activity line, accuracy trend, speed trend, mistake and quality breakdowns, weak-chapter leaderboard, and the syllabus pacing gauge, all filterable by subject and chapter. Account menu, Dashboard.
Study goal and pacing. Set your exam, target, study context, and a pacing goal with a duration that becomes a deadline. Account menu, "Set study goal".
AI Advisor. Data-grounded chat coaching, daily target-setting and day-logging flows, and reminder scheduling. Its own page via the sidebar Advisor card. Needs sign-in and a free Gemini API key.
Daily Reports. Morning target and evening reflection, saved as a dated history. Advisor page, Reports tab (also reachable from the account menu's "Daily Reports").
Reminders and phone pairing. In-app reminders scheduled through the Advisor, optionally mirrored to your phone via the bell icon and a companion Sync ID.
Export Data. JSON export of logged questions by subject or chapter and date range. Account menu.
Backup and Restore. Whole-account JSON download and re-import. Account menu.
Clear Local Data and Wipe Everything. Local-only cache clear versus full irreversible cloud wipe. Account menu.
Theme and layout. Light and dark theme toggle, and a collapsible sidebar that remembers its state. Account menu (theme) and the collapse arrow in the sidebar.
13. UI map
Screen by screen, with the controls on each.
Landing page. The public marketing page with navigation to the blog and FAQ, and an "Open app" button.
Sidebar (left on desktop, a drawer via the hamburger on mobile).
- Top row: app logo, the "LairsFlow" wordmark, and a collapse arrow (desktop) to shrink to icons.
- Subject block: a "Subject" dropdown, and a three-dot menu beside it with Add Subject, Wipe Stats, and Delete Subject (the last two are disabled until a subject is picked).
- Chapter shortcuts: up to three pinned chapter chips, each with a small menu (Star/Unstar, Edit, Reset Log, Delete), plus a "View all" button that opens the full chapter panel.
- Advisor card: "LairsFlow Advisor / Ask your AI coach", opens the Advisor page.
- Account card: "Guest" or your name with a sync dot; opens the account drop-up menu.
Account menu (from the account card). In order: Upload Chapters, Dashboard, Daily Reports, Export Data, Backup All Data, Restore Backup, Toggle Theme, Clear Local Data, Wipe Everything (cloud too), then a divider, then either Sign in with Google and "Set study goal" (signed out) or the sync status, phone-pairing status, "Set study goal", and Sign out (signed in).
Top-right controls. A notification bell used to pair your phone for reminders (enter the companion app's Sync ID).
Timer screen (home). An uppercase hint, the large timer digits, a "tap to start" prompt, a status row, an Undo button, and a minutes:seconds duration editor.
Break / Log screen (after each question). A strip showing time on the question and the next-phase countdown; the "Solved it" / "Didn't get it" fork; the "What happened?" and "Mistake Type" rows for misses; Difficulty; Resource; an optional Question Reference; an optional Notes field with quick chips; and "Save & Next" / "Skip".
Chapter panel ("View all"). The full list of chapters for the selected subject, with per-chapter menus and a "New Chapter" button.
New Session / Edit Session modals. Subject and chapter dropdowns (each with a custom-entry option) to create or edit a chapter.
Upload Chapters modal. A subject name field, a JSON file chooser, a copyable generation prompt, and "Add Chapters".
Export modal. A subject dropdown, a date-range toggle (All time / 7 days / Today), and a list of chapters to export.
Profile / Study Goal modal. Goal exam pills (JEE / NEET / UPSC / Other), target year, study hours per day, strengths and weak spots, coaching-style preference, and the syllabus pacing goal (description plus duration).
Dashboard page. A subject-and-chapter filter row at the top, then KPI cards, session-length cards, the activity heatmap, the activity and accuracy and speed charts, the mistake and quality pies, the weak-chapters leaderboard, and the pacing gauge. Several widgets carry an Overview / Today toggle.
Advisor page. Its own sidebar (New chat, Chat and Reports tabs, a conversation list, and an account trigger), and the chat view with quick-action chips, a data-context menu above the input, and the message box. The Reports tab holds your daily-report history.
14. Example prompts for the Advisor
The Advisor is only as useful as what you ask it, and its strength is your own data. Some prompts that produce grounded, specific answers rather than generic tips:
- "What should I target today?" (proposes a concrete plan from your weak and stale chapters and pacing)
- "Log my day." (walks through an evening reflection and saves a dated report)
- "Am I actually on track for my goal, or am I just covering chapters shallowly?" (reads pacing alongside depth, honestly)
- "Which chapters am I weakest in, and what should I revise first?"
- "Compare the time I actually take per question against my targets. Where am I slowest?"
- "Are my mistakes mostly silly or conceptual, and what does that pattern tell me?"
- "Remind me to start Physics revision at 7pm tonight."
- "I have a family function tomorrow from 10am to 5pm. Plan a light study session around it."
- "Look at my last two weeks. Is my accuracy improving or am I just doing more easy questions?"
15. Where to go next
If you have read this far, you know the whole app. Two good next steps: open LairsFlow and log ten questions on a chapter you know well, just to feel the loop, and then read the dashboard calculations post so every number you see afterwards means exactly what you think it means. Every question is a data point. Vivran v1 is built to make each one count.