FlowState AI is an AI-powered productivity tool designed to help users plan, optimize, and reflect on their daily routines. Instead of acting as a static planner, it combines structured scheduling with AI-driven suggestions to improve how time is used over the long term.
The project focuses on a simple idea: most people don’t struggle to plan their day — they struggle to plan it effectively.
FlowState AI attempts to solve this by:
- automatically structuring tasks into a realistic schedule
- identifying inefficiencies (such as overloaded days)
- providing actionable suggestions using AI
- tracking patterns in how users spend their time
- Create daily schedules using tasks, durations, and priorities
- Automatic break insertion to maintain focus
- Optimized ordering of tasks for better efficiency
- Generate routines from natural language input
- Detect unrealistic schedules and suggest adjustments
- Provide short, actionable tips for each task
- Offer overall feedback on the structure of the day
- Track total productive time
- Visualize how time is distributed across tasks
- Monitor trends and consistency over time
- Secure user login and signup using Firebase Authentication
- Personalized routines tied to individual user accounts
- Save and retrieve routines
- Access data across devices
- Maintain a history of past plans
- Save routines
- View previous routines
- Edit or delete plans
- Organize routines for reuse
- Clean, minimal interface built with Tailwind CSS
- Card-based layout for readability
- Color-coded tasks for clarity
- Designed to be responsive across devices
Frontend
- Next.js (React)
- Tailwind CSS
Backend
- FastAPI (Python)
AI Integration
- Groq (LLaMA-based models)
Database & Authentication
- Firebase (Firestore + Authentication)
Deployment
- Vercel (frontend)
- Hugging Face Spaces (backend)
FlowState-AI/
├── frontend/ # Next.js frontend
├── backend/ # FastAPI backend
│ ├── app/ # Core logic and API routes
│ ├── main.py # Entry point
│ └── requirements.txt
├── hf-deploy/ # Deployment config for Hugging Face
Before running the project locally, ensure you have:
- Python 3.9+
- Node.js (v16 or later)
- npm or yarn
- A Groq API key
- A Firebase project (Firestore + Authentication enabled)
git clone https://github.com/Akul321/FlowState-AI.git
cd FlowState-AI
cd backend
python -m venv venv
venv\Scripts\activate # On Windows
pip install -r requirements.txt
Create a .env file:
GROQ_API_KEY=your_key_here
FIREBASE_SERVICE_ACCOUNT_JSON=your_json_here
ALLOWED_ORIGINS=http://localhost:3000
Run the backend:
uvicorn main:app --reload
cd frontend
npm install
npm run dev
Open:
http://localhost:3000
| Variable | Description |
|---|---|
GROQ_API_KEY |
API key used for AI-generated responses |
FIREBASE_SERVICE_ACCOUNT_JSON |
Firebase admin credentials |
ALLOWED_ORIGINS |
CORS configuration for frontend-backend communication |
-
Hybrid system (logic + AI): Scheduling is handled deterministically, while AI is used for suggestions. This ensures reliability without over-relying on AI.
-
Separation of concerns: Frontend, backend, and AI components are clearly separated for scalability and maintainability.
-
User-centric design: The interface is kept minimal so users can focus on planning rather than navigating the tool.
- Integrating AI meaningfully rather than just generating text
- Managing real-time interaction between frontend and backend
- Deploying across multiple platforms while keeping everything within free tiers
- Timeline-based schedule visualization
- More advanced analytics and trend tracking
- Personalized AI suggestions based on user history
- Integration with calendars and reminders
- Mobile-first optimization / PWA support
This project was an exploration of how AI can be applied to everyday decision-making. It helped me understand how to combine traditional system design with AI components to build something that is both practical and scalable.
It also reinforced the importance of designing tools that don’t just provide information, but help users improve over time.
This project is open-source and available under the MIT License.