MindFlow is a modern full-stack web application designed to help individuals and teams track, analyze, and optimize daily productivity. Through intelligent time management, habit tracking, and AI-powered insights, everyone can become a productivity master.

• Data-Driven: Make decisions based on real data, not assumptions
• Habit-First: Achieve long-term goals through continuous small improvements
• Simple & Intuitive: Elegant interface design with zero learning curve
• Privacy-Protected: Your data stays under your control with self-hosting support

One-command start (requires Docker) git clone https://github.com/yourusername/mindflow.git cd mindflow docker-compose up -d

Access the app open http://localhost:5173

text

• 📤 Data Export (PDF/CSV/JSON)
• 🍅 Pomodoro Timer Integration
• 🔔 Smart Reminders and Notifications
• 👥 Team Collaboration Features
• 📅 Calendar Integration
• 🌐 Multi-language Support
• 📲 Mobile App (React Native)
• 🔐 User Authentication System

mindflow/ ├── 📁 backend/ # Backend service │ ├── main.py # FastAPI main app (259 lines) │ ├── models.py # Data models & schemas │ ├── ai_insights.py # AI analysis module │ ├── requirements.txt # Python dependencies │ └── Dockerfile # Backend container config │ ├── 📁 frontend/ # Frontend application │ ├── src/ │ │ ├── App.jsx # Root component │ │ ├── components/ │ │ │ └── Dashboard.jsx # Dashboard (400 lines) │ │ ├── api.js # API client │ │ └── main.jsx # Entry point │ ├── index.html # HTML template │ ├── package.json # Node dependencies │ ├── vite.config.js # Vite config │ └── Dockerfile # Frontend container config │ ├── docker-compose.yml # Docker orchestration ├── .env.example # Environment variable template ├── LICENSE # Apache 2.0 license └── README.md # Project documentation (this file)

text

┌─────────────────────────────────────────────────────────────┐ │ UI Layer │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ Overview │ │ Activities │ │ Habits │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ Goals │ │ Charts │ │ AI Insights │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ └────────────────────┬────────────────────────────────────────┘ │ React + Vite + TailwindCSS │ ┌────────────────────┴────────────────────────────────────────┐ │ API Layer │ │ ┌──────────────────────────────────────────────────────┐ │ │ │ FastAPI RESTful API │ │ │ │ /activities /habits /goals /analytics │ │ │ └──────────────────────────────────────────────────────┘ │ └────────────────────┬────────────────────────────────────────┘ │ ┌────────────────────┴────────────────────────────────────────┐ │ Business Logic Layer │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ SQLAlchemy │ │ Pydantic │ │ OpenAI API │ │ │ │ ORM │ │ Validation │ │ AI Analysis │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ └────────────────────┬────────────────────────────────────────┘ │ ┌────────────────────┴────────────────────────────────────────┐ │ Data Persistence Layer │ │ ┌──────────────────────────────────────────────────────┐ │ │ │ SQLite Database (extensible to PostgreSQL) │ │ │ │ activities | habits | goals | analytics │ │ │ └──────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────┘

text

Choose your installation method:

• ✅ Docker >= 20.10
• ✅ Docker Compose >= 2.0

• ✅ Python >= 3.12
• ✅ Node.js >= 18.0
• ✅ npm or yarn

1. Clone the project git clone https://github.com/yourusername/mindflow.git cd mindflow

2. Configure environment (optional) cp .env.example .env

Edit .env to add your OpenAI API Key (if you want AI features) 3. Start all services docker-compose up -d

4. Check service status docker-compose ps

5. View logs docker-compose logs -f

6. Stop services docker-compose down

text

Backend:

Enter backend directory cd backend

Create virtual environment python -m venv venv

Activate virtual environment Linux/Mac: source venv/bin/activate

Windows: venv\Scripts\activate

Install dependencies pip install -r requirements.txt

Start backend service python main.py

Or use uvicorn uvicorn main:app --reload --host 0.0.0.0 --port 8000

text

Frontend:

New terminal, enter frontend directory cd frontend

Install dependencies npm install

or yarn install

Start dev server npm run dev

or yarn dev

text

Once running, visit:

• 🌐 Frontend UI: http://localhost:5173
• 🔧 Backend API: http://localhost:8000
• 📚 API Docs: http://localhost:8000/docs (Swagger UI)
• 📖 Alternative Docs: http://localhost:8000/redoc (ReDoc)

Create activity POST /api/activities Content-Type: application/json

{ "category": "Work", "description": "Write project documentation", "duration": 60, "productivity_score": 8 }

Get activity list GET /api/activities?skip=0&limit=100

Get today's statistics GET /api/activities/today

text

Create habit POST /api/habits Content-Type: application/json

{ "name": "Morning reading", "target_frequency": 7 }

Get habit list GET /api/habits

Mark habit complete POST /api/habits/{habit_id}/complete

text

Create goal POST /api/goals Content-Type: application/json

{ "title": "Learn Python", "description": "Complete FastAPI course", "target_hours": 20, "deadline": "2025-12-31T23:59:59Z" }

Get goal list GET /api/goals

Update goal progress PUT /api/goals/{goal_id}/progress Content-Type: application/json

{ "hours": 2 }

text

Get weekly analytics GET /api/analytics/weekly

text

{ "id": 1, "category": "Work", # Category: Work/Learning/Exercise/Social/Entertainment/Chores "description": "Write code", # Description "duration": 60, # Duration (minutes) "productivity_score": 8.0, # Productivity score (1-10) "start_time": "2025-12-26T10:00:00Z" # Start time }

text

{ "id": 1, "name": "Morning meditation", # Habit name "target_frequency": 7, # Target frequency (times per week) "current_streak": 15, # Current streak (days) "best_streak": 30, # Best streak "last_completed": "2025-12-26T08:00:00Z" # Last completion time }

text

{ "id": 1, "title": "Complete project", # Goal title "description": "...", # Description "target_hours": 50, # Target hours "current_hours": 25, # Current hours logged "progress": 50.0, # Progress percentage "deadline": "2025-12-31T23:59:59Z", # Deadline "completed": false # Completion status }

text

Steps:

1. Switch to "Activities" tab
2. Select activity category
3. Enter description and duration
4. Slide to set productivity score (1-10)
5. Click "Log Activity"

Tip: Log activities promptly for more accurate analysis.

Steps:

1. Go to "Habits" tab
2. Create new habit, set target frequency
3. Click "Mark as Done Today" after completion each day
4. Watch your streak grow

Tip: Consecutive completions earn the "fire" badge—keep the streak alive!

Steps:

1. Open "Goals" tab
2. Fill in goal title, description, target hours
3. Set deadline
4. System automatically tracks progress based on logged activities

Tip: Set specific, measurable goals for better results.

Features:

• 📈 Weekly time trends
• 📊 Category time distribution
• 🎯 Productivity score trends
• 🔥 Habit completion status
• 📋 Goal progress overview

Create a .env file and configure:

OpenAI API Configuration (optional - for AI insights) OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Database Configuration DATABASE_URL=sqlite:///./mindflow.db

PostgreSQL example: DATABASE_URL=postgresql://user:password@localhost:5432/mindflow API Server Configuration API_HOST=0.0.0.0 API_PORT=8000 API_RELOAD=true

Frontend Configuration VITE_API_URL=http://localhost:8000

Log Level LOG_LEVEL=INFO

CORS Configuration (restrict in production) CORS_ORIGINS=["http://localhost:5173"]

text

DATABASE_URL=sqlite:///./mindflow.db

text

1. Install PostgreSQL driver pip install psycopg2-binary

2. Update environment variable DATABASE_URL=postgresql://username:password@localhost:5432/mindflow

3. Create database createdb mindflow

text

1. Install MySQL driver pip install pymysql

2. Update environment variable DATABASE_URL=mysql+pymysql://username:password@localhost:3306/mindflow

text

1. Visit OpenAI Platform
2. Create an API key
3. Add to .env file:

OPENAI_API_KEY=sk-your-api-key-here

text

Note: AI features are optional. MindFlow works fine without them.

Enter backend directory cd backend

Install test dependencies pip install pytest pytest-cov httpx

Run tests pytest

With coverage report pytest --cov=. --cov-report=html

View coverage report open htmlcov/index.html

text

Enter frontend directory cd frontend

Install test dependencies npm install --save-dev vitest @testing-library/react

Run tests npm test

With coverage npm test -- --coverage

text

Test API with curl Health check curl http://localhost:8000/

Create activity curl -X POST http://localhost:8000/api/activities -H "Content-Type: application/json" -d '{ "category": "Work", "description": "API test", "duration": 30, "productivity_score": 8 }'

Get today's stats curl http://localhost:8000/api/activities/today

text

1. Build production images docker-compose -f docker-compose.prod.yml build

2. Start services docker-compose -f docker-compose.prod.yml up -d

3. View logs docker-compose -f docker-compose.prod.yml logs -f

4. Scale services (load balancing) docker-compose -f docker-compose.prod.yml up -d --scale backend=3

text

/etc/nginx/sites-available/mindflow upstream backend { server localhost:8000; }

server { listen 80; server_name mindflow.example.com;

text

location / { root /var/www/mindflow/frontend/dist; try_files $uri $uri/ /index.html; }

location /api { proxy_pass http://backend; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; }

location /ws { proxy_pass http://backend; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; } }

text

/etc/systemd/system/mindflow-backend.service [Unit] Description=MindFlow Backend Service After=network.target

[Service] Type=simple User=www-data WorkingDirectory=/opt/mindflow/backend Environment="PATH=/opt/mindflow/backend/venv/bin" ExecStart=/opt/mindflow/backend/venv/bin/uvicorn main:app --host 0.0.0.0 --port 8000 Restart=always

[Install] WantedBy=multi-user.target

text

Install Vercel CLI npm i -g vercel

Deploy frontend cd frontend vercel --prod

text

Install Railway CLI npm i -g @railway/cli

Login and initialize railway login railway init

Deploy railway up

text

Create app heroku create mindflow-app

Add database heroku addons:create heroku-postgresql:hobby-dev

Deploy git push heroku main

text

Backend debug mode export LOG_LEVEL=DEBUG python backend/main.py

View detailed SQL queries export SQLALCHEMY_ECHO=True

Frontend debug mode npm run dev -- --debug

Docker log tracking docker-compose logs -f --tail=100

Inspect database contents sqlite3 backend/mindflow.db

.tables SELECT * FROM activities;

text

We welcome all forms of contributions!

1. Fork the project
2. Create feature branch (git checkout -b feature/AmazingFeature)
3. Commit changes (git commit -m 'Add some AmazingFeature')
4. Push to branch (git push origin feature/AmazingFeature)
5. Open Pull Request

Format with Black pip install black black backend/

Sort imports with isort pip install isort isort backend/

Check with flake8 pip install flake8 flake8 backend/ --max-line-length=100

text

Format with Prettier npm install --save-dev prettier npx prettier --write frontend/src/

Check with ESLint npm install --save-dev eslint npx eslint frontend/src/

text

Use Conventional Commits standard:

feat: add new feature fix: fix bug docs: update documentation style: code formatting refactor: code refactoring test: add tests chore: build tools or dependency updates

text

Examples: feat(habits): add habit grouping feature fix(api): fix validation error on activity creation docs(readme): update installation instructions

text

This project is licensed under Apache License 2.0 - see LICENSE file for details

Copyright 2025 MindFlow Contributors

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

text http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

text

Thanks to these excellent open source projects:

• FastAPI - Modern, fast Web framework
• React - UI building library
• TailwindCSS - Utility-first CSS framework
• Recharts - React-based charting library
• SQLAlchemy - Python SQL toolkit
• Docker - Container platform

• RescueTime - Time tracking inspiration
• Habitica - Habit gamification
• Notion - Product design inspiration
• Todoist - Goal management patterns

• GitHub: @yourusername
• Email: your.email@example.com
• Twitter: @yourusername

• 💬 GitHub Discussions - Questions and discussions
• 🐛 GitHub Issues - Report bugs
• 📧 Email: support@mindflow.app
• 💬 Discord: Join community

• Official Website
• Documentation
• Blog
• Changelog

• Basic time tracking
• Habit management
• Goal setting
• Data visualization
• AI insights (optional)
• Dark mode
• Responsive design

• Pomodoro timer
• Data export (PDF/CSV)
• Notification system
• Multi-language support
• Performance optimization

• User authentication system
• Team collaboration features
• Mobile app
• Calendar integration
• Third-party app integration
• Advanced data analytics

View full roadmap: ROADMAP.md

• FastAPI Complete Tutorial
• React Official Documentation
• TailwindCSS Documentation
• Docker Getting Started Guide
• SQLAlchemy ORM

• Time Tracking Tools Comparison
• Productivity Tools Collection
• Self-Hosted Applications