An intelligent, pattern-learning task scheduler that adapts in real time to your personal working rhythm — not a generic to-do list.
FlowMind AI doesn't just record what you need to do. It watches when you actually finish things, where you tend to procrastinate, and how accurate your own time estimates are — then feeds all of that back into Google Gemini on every single planning call, so each new task is scheduled a little smarter than the last one.
Built for the Google AI Studio "Last-Minute Life Saver" Hackathon (Vibe-2-Ship).
- Why FlowMind Is Different
- Architecture & Cognitive Loop
- Feature Reference
- The Interactive Demo Flow
- Tech Stack
- Project Structure
- Setup & Running Locally
- Gemini API Endpoints
- Offline Resilience
- Known Limitations
- Evaluation Mapping
Most scheduling tools apply the same generic formula to every user: divide total hours by days remaining, done. FlowMind instead treats scheduling as a continuous, observable, agentic loop:
You give it a task FlowMind explains WHY You complete or miss it
│ it chose each slot │
▼ ▲ ▼
Gemini analyzes ───────────────────┘ Pattern data updates
your history, (peak hours, skip
builds a schedule rates, estimation
│ accuracy)
└──────────────────────────────────────────────────────┘
Next task is scheduled smarter
Every scheduled block carries a Decision Justification ("Why this slot?") instead of being an opaque output. Every risky pattern — burnout, deadline pile-ups, context-switching overload — is flagged before it becomes a missed deadline, not after.
┌─────────────────────────────┐
│ User Task + Deadline Input │
└───────────────┬─────────────┘
│
▼
┌──────────────────────────────────────┐
│ Pattern Tracker Context Injected │
│ (peak hours, procrastination slots, │
│ estimation accuracy, streaks) │
└───────────────────┬──────────────────┘
│
▼
┌──────────────────────────────────────┐
│ Express API Proxy (server.ts) │
│ Secures GEMINI_API_KEY server-side │
└───────────────────┬──────────────────┘
│
┌─────────────┴──────────────┐
│ │
▼ ▼
┌──────────────────────┐ ┌─────────────────────────┐
│ Google Gemini API │ │ 429 / network error? │
│ (structured JSON │ │ Fall back to local │
│ schema response) │ │ mathematical scheduler│
└──────────┬───────────┘ └────────────┬────────────┘
│ │
└───────────────┬───────────────┘
▼
┌───────────────────────────────┐
│ Active Sprint Scheduled │
│ (each block has a "Why this │
│ slot?" justification) │
└───────────────┬───────────────┘
┌────────┴─────────┐
▼ ▼
[ ✅ Done ] [ ❌ Missed ]
│ │
▼ ▼
Log actual hours & Recovery Mode: auto-
completion time redistributes remaining
│ hours, shows new ETA
▼ │
Update Pattern History ◄────────┘
(heatmap, accuracy,
skip-rate per slot)
│
▼
┌─────────────────────────────┐
│ Next Planning Cycle │
│ (Gemini is now smarter about│
│ YOUR pace) │
└─────────────────────────────┘
Why this counts as agentic, not just "an LLM call":
- Persistent memory —
localStorageholds completion history, peak hours, and procrastination slots, which are compiled into a context string and re-injected into every Gemini call (seeGeminiAgent.getUserPatternSummary()). - Self-explaining output — the structured response schema requires a
reasoningfield and per-block justifications, so the model's "thinking" is always visible, not hidden behind a black box. - Closed feedback loop —
learnFromCompletion()sends actual-vs-estimated hours back to Gemini, which returns a fresh behavioral insight that's stored and surfaced in the UI ("What I've Learned"). - Graceful degradation — if Gemini is rate-limited or unreachable, a deterministic local scheduler takes over so the user experience never breaks, and the UI is honest about which mode produced the schedule.
Every scheduled focus block displays a "Why this slot?" explanation generated from real tracked data — not boilerplate text:
- If the slot lands on a known weak time (a day/hour where you've previously missed sessions), FlowMind is honest about it: "This is normally a weak time, but I had to schedule here due to limited availability — consider a reminder."
- If the slot avoids a weak time, it explains why it's safe: "Wednesday 6pm is a safe time — you historically complete tasks consistently here."
- If the slot lands in your detected peak-productivity window, it notes the speed advantage.
- If the block is scheduled with deadline buffer, it explains the safety margin.
This logic deliberately avoids the contradiction bug found in earlier builds (saying "avoiding X" while scheduling directly on X) — the explanation now always matches what was actually scheduled.
When 3 or more deadlines cluster within a 7-day window, FlowMind proactively surfaces a warning showing total hours required, days available, and hours/day workload — with a recommendation to extend, reduce scope, or request an extension, before the user discovers the conflict the hard way.
When a user is juggling 3+ active tasks across 3+ different task types (e.g. coding + writing + design simultaneously), FlowMind applies a research-grounded 25% time buffer to account for the cognitive cost of switching contexts, and explains the adjustment transparently rather than silently inflating estimates.
If scheduled hours for the current week exceed 40 hours combined with 3+ distinct task types, FlowMind flags a burnout risk and offers a one-click 60/40 redistribution across this week and next — keeping the user on track for the deadline while protecting sustainable pace.
Clicking ❌ Missed on any block doesn't just log a failure — it opens a Recovery Mode panel that recalculates the remaining schedule, shows exactly how many days the completion date will slip, and lets the user accept the new plan with one click. No panic, no manual re-planning.
Once 2+ tasks are completed, the Patterns tab shows an Estimation Accuracy Trend per task type — comparing actual vs. estimated hours for recent completions and showing whether the system's predictions are improving or need adjustment. This is the most direct, visible proof that the AI is learning, not just templating.
Missed sessions are aggregated by day-of-week and hour into a Procrastination Hotspots panel showing skip-rate percentages with color-coded risk (🔴 60%+, 🟡 30–60%, 🟢 <30%) — turning raw missed-session logs into an actionable, visible pattern instead of leaving them buried in localStorage.
A guided, 5-step modal walkthrough (see below) lets anyone evaluating the app see the full agentic loop — task creation, live AI reasoning, schedule generation, and visible adaptation on a second task — in under two minutes, without needing to manually populate test data.
A small circular gauge in the header tracks API requests against the free-tier per-minute limit and resets automatically every 60 seconds, so heavy testing sessions don't silently degrade the experience without warning.
Anyone can click "Continue as Guest →" to skip straight into the same onboarding flow (peak-hours selection) as an authenticated user — removing all friction for first-time evaluators.
A full theme system (Settings → Dark/Light toggle) repaints the entire interface via scoped CSS overrides, persisted to localStorage, without requiring every individual component to be rewritten with conditional class logic.
A monthly calendar (Plan → Calendar tab) renders colored dots for every scheduled block across all active tasks, supports forward/backward month navigation plus a one-click Today button, and highlights the current date with an emerald ring.
The entire interface — onboarding, dashboard, task planner, pattern analytics, and calendar — is built with responsive Tailwind breakpoints, so it works directly in a phone browser with no separate app required. Layouts reflow from multi-column to stacked single-column views, touch targets are sized for tap input, and the experience stays fully usable on screens as narrow as a standard smartphone viewport.
Click "🎬 Watch Interactive Demo (2 min)" directly below the main scheduling button (no need to dig through settings) to trigger:
┌──────────────────────────────────────────────────────────────┐
│ ON CLICK: Background dashboard data is seeded immediately │
│ — 5 realistic past completions, a populated heatmap, peak │
│ hours, and 2 pre-existing tasks at different risk levels — │
│ so Patterns and Calendar are already rich with data. │
└───────────────────────────┬──────────────────────────────────┘
▼
┌──────────────────────────────────────────────────────────────┐
│ STEP 1 — Add Your First Task │
│ "Finish Project Report & Submit to Client" (due in 3 days) │
└───────────────────────────┬──────────────────────────────────┘
▼
┌──────────────────────────────────────────────────────────────┐
│ STEP 2 — Watch AI Planning │
│ Live reasoning log: complexity, pattern check, pace, │
│ risk assessment, schedule construction │
└───────────────────────────┬──────────────────────────────────┘
▼
┌───────────────────────────────────────────────────────────────┐
│ STEP 3 — Schedule Generated → task is added to Active Sprints│
│ Blocks shown aligned to peak hours, with deadline buffer │
└───────────────────────────┬───────────────────────────────────┘
▼
┌──────────────────────────────────────────────────────────────┐
│ STEP 4 — Add a Second, Different Task │
│ "Study for Midterm Exam" (due in 9 days, different type) │
└───────────────────────────┬──────────────────────────────────┘
▼
┌─────────────────────────────────────────────────────────────┐
│ STEP 5 — "FlowMind Just Learned Something" │
│ Explicitly shows what was learned from task #1 and how it │
│ shaped the schedule for task #2 → task added to Active │
│ Sprints, demo ends, user is free to keep exploring │
└─────────────────────────────────────────────────────────────┘
By the end of the walkthrough, the evaluator has: a Patterns tab full of heatmap and accuracy data, a Calendar populated with task dates, 4 tasks in Active Sprints spanning all 3 risk levels, and — if they keep exploring — a live demonstration of Deadline Cliff Detection and Context-Switching Detection, since the combined demo + walkthrough tasks naturally cross both thresholds.
Note for evaluators: the demo can be safely re-run multiple times; each run re-seeds the same deterministic dataset rather than accumulating duplicates.
| Layer | Technology |
|---|---|
| Frontend framework | React 19 + TypeScript |
| Styling | Tailwind CSS v4 (@tailwindcss/vite) |
| Animation | motion (Framer Motion successor) |
| Icons | lucide-react |
| Build tool | Vite 6 |
| Backend runtime | Express.js on Node, bundled with esbuild |
| AI engine | Google Gemini API (@google/genai) |
| Persistence | Browser localStorage (no database — fully client-resident) |
| Dev runtime | tsx (TypeScript execution without a separate compile step) |
flowmind-ai/
├── server.ts # Express app + 5 Gemini-backed API routes
│ # + deterministic offline fallback scheduler
├── src/
│ ├── App.tsx # Main UI — single-page app with 5 tabs
│ │ # (Plan, AI, Calendar, Patterns, Reminders)
│ ├── index.css # Tailwind entrypoint + light/dark theme overrides
│ ├── main.tsx # React root mount
│ ├── types.ts # Shared TypeScript interfaces
│ └── services/
│ ├── geminiAgent.ts # Client-side agent: analyzeTask, learnFromCompletion,
│ │ # generateSmartReminder, request caching, client-side
│ │ # fallback scheduler for true network failures
│ ├── patternTracker.ts # localStorage-backed pattern persistence layer
│ └── fetchHelper.ts # Shared fetch wrapper (custom API key header injection)
├── index.html
├── package.json
├── tsconfig.json
├── vite.config.ts
└── .env.example # GEMINI_API_KEY / APP_URL placeholders
- Node.js 18+
- A Gemini API key from aistudio.google.com (free tier works, see Known Limitations for rate-limit notes)
npm install
# Create a .env file with your key:
echo 'GEMINI_API_KEY="your_key_here"' > .env
npm run dev
# → Server running at http://localhost:3000Alternatively, paste your key directly into the in-app Settings ⚙️ → API Key field — it's sent as a request header and never persisted server-side.
npm run build # Vite client build + esbuild server bundle → dist/
npm start # Runs the bundled servernpm run lint # tsc --noEmitAll routes live in server.ts and require a valid GEMINI_API_KEY (server .env) or a per-request X-Gemini-Key header (Settings panel key).
| Endpoint | Purpose |
|---|---|
POST /api/gemini/analyze-task |
Core scheduling call. Takes task name, deadline, and a compiled user-pattern summary; returns a structured schedule with reasoning, risk level, milestones, and a completion prediction. |
POST /api/gemini/learn-completion |
Called when a task is finished or a sprint is closed. Sends actual-vs-estimated hours and on-time rate; returns a fresh behavioral insight. |
POST /api/gemini/generate-reminder |
Generates a context-aware nudge based on hours remaining, completion percentage, and current milestone. |
POST /api/gemini/analyze-calendar |
Analyzes manually-entered busy times to inform scheduling constraints. |
POST /api/gemini/reschedule-task |
Recalculates a schedule mid-flight (e.g. after a busy-time update). |
All five use Gemini's structured JSON response schema (responseMimeType: "application/json" with an explicit schema) rather than free-text parsing, which is what makes the reasoning and schedule fields reliably structured for the UI to render.
If a Gemini call returns a 429 (quota exceeded) or any other error, server.ts transparently falls back to a deterministic local scheduler (generateOfflineFallbackSchedule) rather than failing the request:
- Computes the exact number of calendar days between now and the deadline (normalized to day boundaries to avoid off-by-one errors).
- Spreads the estimated hours evenly across those days, capped at a sensible max of 9 hours/day and 3 hours/block.
- Skips weekends when there's enough runway to do so, falls back to using them when the deadline is tight.
- Schedules only before the deadline — never past it.
- Labels the response honestly: "⚡ Offline Mode: Using Mathematical Scheduler... The result is the same — you get a smart schedule — just without the live AI reasoning."
This was verified directly by calling the endpoint with an invalid key and checking the response for a same-day deadline, a 2-day deadline, and a 30-day deadline — all produced correctly-bounded schedules with no dates beyond the requested deadline.
A second, independent fallback exists client-side in geminiAgent.ts (generateOfflineSchedule) for the rarer case where the network request to the Express server itself fails (not just a Gemini-side error) — it generates an interval-based schedule directly in the browser so the app remains usable even if the backend is fully unreachable.
- Voice input uses the native Web Speech API. It does not function inside the AI Studio iframe preview (browsers block microphone access in nested iframes) but works normally in a standalone browser tab.
- Google Calendar / Tasks / Drive integration is intentionally manual — busy times are entered by the user rather than pulled via OAuth, to keep the demo self-contained and avoid OAuth setup friction for evaluators.
- Free-tier Gemini quota is shared across all 5 endpoints and is fairly easy to exhaust during heavy manual testing; the offline fallback exists specifically so this never blocks evaluation.
- Light mode is implemented via scoped CSS class overrides rather than a full design-token rewrite, so a small number of low-opacity accent backgrounds (e.g. translucent warning-card tints) may render slightly differently than a from-scratch light theme — functionally complete, cosmetically secondary.
| Criterion | How FlowMind Addresses It |
|---|---|
| Problem Solving & Impact | Directly targets missed deadlines and poor self-estimation with visible, quantified impact metrics (on-time rate, deadline buffer, accuracy trend) rather than abstract claims. |
| Agentic Depth | Five specialized Gemini endpoints, persistent cross-call memory, self-explaining structured output, and a genuine closed learning loop (completion → insight → next schedule). |
| Innovation & Creativity | Predictive deadline-cliff and context-switching detection, burnout prevention with one-click redistribution, and honest decision justification per scheduled block — going beyond "AI fills in a calendar." |
| Google Technologies | Deep, structured use of the Gemini API (JSON schema responses, multi-turn pattern injection) across five distinct reasoning tasks, not a single wrapper call. |
| Product Experience & Design | Responsive single-codebase layout, dark/light theming, guest mode for zero-friction evaluation, and a guided interactive demo that explains the agentic loop in under two minutes. |
| Technical Implementation | Fully typed TypeScript front-to-back, secure server-side API key proxying, deterministic offline fallback verified against multiple deadline scenarios, clean tsc --noEmit and production build. |
| Completeness & Usability | End-to-end flow — continue as Guest, add a task, see a justified schedule, mark blocks done or recover from missed ones, watch patterns accumulate — works without any manual setup. |
FlowMind AI — because a deadline reminder shouldn't be the only thing your scheduler is good for.