Clarity

Inspiration

Most productivity apps treat every day the same — they hand you a static list and expect you to power through it regardless of how you're actually feeling. But real life isn't like that. Some days you're sharp and energized; others you're running on empty. I wanted to build something that adapts — a personal operating system that knows your current state and helps you work with it, not against it.

What it does

Clarity is a mobile-first adaptive productivity app. Each day starts with a 5-second check-in: you rate your energy, stress, mood, and focus, and say how much time you have. From that snapshot, the app:

• Generates a personalized daily briefing and detects your current "mode" (normal / low energy / high stress / recovery)
• Surfaces a Best Next Action — the single task most suited to how you feel right now
• Scores and reorders your task list using a priority engine that weighs urgency, importance, energy required, and time available against your check-in
• Tracks daily habits with streaks
• Lets you brain-dump anything on your mind and auto-organizes it into tasks
• Runs a focus timer that persists across navigation

How we built it

I used a contract-first approach: the OpenAPI spec was written first, then React Query hooks and Zod schemas were generated from it automatically using Orval. The frontend is React + Vite + Tailwind CSS, routing with Wouter. The backend is Express 5 with Drizzle ORM on PostgreSQL. The priority engine is a pure rule-based scoring function — no AI dependency required — that computes a weighted score for each task using urgency, importance, energy match, and time match relative to the current check-in.

Challenges we ran into

• Getting the adaptive priority engine to feel intuitive rather than arbitrary required careful weight tuning across the four scoring dimensions.
• Designing a check-in UX that was genuinely fast (under 10 seconds) without losing expressiveness — ended up with filled pill buttons that read like mini progress bars.
• Keeping the focus timer alive across React navigation required lifting timer state into a global context so it persists when the component unmounts.
• Ordering Express routes correctly so /checkins/latest never gets shadowed by /checkins/:id was a subtle but breaking bug early on.

Accomplishments that we're proud of

• Built a fully working adaptive priority engine from scratch — no AI APIs, no black box. It scores every task in real time using a weighted formula across urgency, importance, energy match, and time fit, then cross-references your check-in state to surface exactly the right next action for how you feel right now.

• Designed a check-in experience that takes under 10 seconds. Getting that fast without losing expressiveness required several iterations — the final pill-button layout that fills like a progress bar was a genuine UX breakthrough.

• Achieved a fully contract-first architecture: the OpenAPI spec is the single source of truth, and all React Query hooks, TypeScript types, and Zod validation schemas are auto-generated from it. Any API change propagates end-to-end with one command.

• The focus timer persists across navigation — it keeps counting down in a global React context even when you switch to another tab, which turned out to require careful architectural thinking around component lifecycle.

• Shipped a complete, polished, multi-page mobile-first PWA — dashboard, check-in, tasks, brain dump, focus timer, habits, insights, and completed tasks — all in a single hackathon session.

What we learned

• I learned how to structure a real full-stack app for the first time — a separate frontend, a backend API, and a database, all talking to each other. Seeing it actually work end to end was a huge confidence boost.

• I learned that thinking through your API before writing any code saves a ton of time. Deciding what data the frontend needs upfront meant I wasn't constantly rewriting things to match.

• React state management clicked for me on this project. I ran into a bug where my focus timer would reset every time I changed pages — fixing it taught me that some state needs to live at the app level, not inside a single screen.

• I learned that small UX decisions have a big impact. I originally had large clunky buttons for the check-in — shrinking them down made the whole interaction feel faster and more natural, without changing any functionality.

• Working with a database for the first time was intimidating, but Drizzle ORM made it approachable. Writing my tables in TypeScript and having them automatically match my code was much easier than I expected.

• Most importantly, I learned that you can build something genuinely useful without knowing everything. Starting small, solving one problem at a time, and iterating got me a lot further than trying to plan the perfect app upfront.

What's next for Clarity

• AI-powered briefings — replace the rule-based mode detection with an LLM that reads your check-in history and generates a genuinely personalized daily narrative.

• Recurring tasks and smart scheduling — let tasks repeat on a cadence and auto-schedule them into your available time based on your check-in energy pattern.

• Notifications and reminders — push notifications for habit check-ins, focus session nudges, and end-of-day reflections via a PWA service worker.

• Calendar integration — pull in calendar events so the available-time calculation accounts for your actual schedule, not just what you estimate.

• Long-term pattern learning — analyze weeks of check-in data to surface personal insights like "you focus best Tuesday mornings" or "high stress always follows low sleep."

• Offline-first support — cache check-ins and tasks locally so the app works without a connection and syncs when back online.

• Shared accountability — optionally share habit streaks or focus session stats with a friend or accountability partner.

Built With

• drizzle-orm
• express-5
• node.js-24
• orval(openapi-codegen)
• pnpm-workspace
• postgresql
• react
• replit
• tailwindcss
• tanstack-react-query
• typescript
• vite
• wouter
• zod