habitflow

Flask Python SQLite HTML/CSS JavaScript App Hub Shared Backend App Hub Shared UI Form Validation Service

habits productivity tracking streaks analytics self-improvement motivation

Database

HabitFlow 🎯

A beautiful habit tracking application with GitHub-style heatmaps, streak tracking, and motivating analytics.

Features

✨ Core Features

• Habit Management: Create, update, and delete habits with custom names, categories, and emojis
• Daily Logging: Log habit completions with a single click
• Streak Tracking: Automatically calculates current and longest streaks
• Completion Heatmaps: GitHub-style visualization of habit completion over the last 90 days
• Analytics Dashboard: View completion rates for 7, 30, and 90-day periods
• Category Organization: Organize habits by category (health, fitness, learning, etc.)
• Global Overview: See at-a-glance stats across all your habits

📊 Visual Elements

• GitHub-inspired heatmap showing completion history
• Animated streak indicators with fire emoji 🔥
• Color-coded category badges
• Progress bars for completion rates
• Responsive design that works on desktop and mobile

🎯 Categories

• General
• Health
• Fitness
• Learning
• Productivity
• Mindfulness
• Social
• Creative
• Finance

Tech Stack

• Backend: Flask + App Hub Shared Backend
• Database: SQLite (via DatabaseManager)
• Frontend: HTML + Shared CSS + Vanilla JavaScript
• Validation: Form Validation Service (app-hub/shared_backend/validators.py)

How to Run

cd ~/projects/habitflow
python3 app.py

The app will start and be accessible at the auto-allocated port (typically in the 5100-6000 range).

Usage

Creating a Habit

1. Enter a habit name (e.g., "Morning meditation", "Read 30 minutes") 2. Choose a category to organize your habits 3. Pick an emoji to represent your habit 4. Set your target days (how many days per week you aim for) 5. Click "Create Habit"

Tracking Progress

• Click "Log Today" to mark a habit as complete for today
• The streak will automatically update
• If you made a mistake, click "✓ Done" to un-log today's entry

Viewing Analytics

Click the "📊 Analytics" button on any habit to see:

• Current and longest streak
• 7, 30, and 90-day completion rates
• A 90-day heatmap showing your completion history

Managing Habits

• Edit: Click on a habit to modify its details (name, category, emoji, target days)
• Delete: Click "Delete" to remove a habit (this is a soft delete - data is preserved)

API Endpoints

Habits

• GET /api/habits - List all active habits with streak data
• POST /api/habits - Create a new habit
• PUT /api/habits/ - Update a habit
• DELETE /api/habits/ - Delete a habit

Logging

• POST /api/habits//log - Log a habit completion
• DELETE /api/habits//log - Remove today's log

Analytics

• GET /api/habits//analytics - Get detailed analytics for a habit
• GET /api/analytics - Get global analytics across all habits
• GET /api/categories - Get valid category list

Example Request Body (Create Habit)

{
  "name": "Morning meditation",
  "category": "mindfulness",
  "emoji": "🧘",
  "target_days": 7
}

Data Persistence

All data is stored in SQLite via the App Hub DatabaseManager:

• Habits table: Stores habit definitions
• Habit logs table: Stores completion timestamps

Data is persisted between app restarts.

Design Decisions

Why Heatmaps?

GitHub's contribution graph is a powerful visual motivator. Seeing a row of green squares encourages you to keep the streak going. HabitFlow brings this same motivational technique to personal habits.

Streak Calculation

• Current streak: Counts consecutive days up to today. Breaks if a day is missed.
• Longest streak: Tracks the maximum consecutive days ever achieved.

Completion Rate

Shows the percentage of days completed over 7, 30, and 90-day periods. This gives you a sense of overall performance beyond just current streaks.

Categories

Categories help organize habits by area of life and allow for color-coded visual distinction. Categories are also useful for filtering and analytics (future features).

Future Enhancements

Potential improvements:

• Filtering habits by category
• Weekly/monthly goals with visual progress
• Reminders or notifications
• Export data as CSV
• Streak competitions with friends
• Habit templates (pre-defined habits)
• Custom reminder times
• Achievement badges for milestones

License

Created as part of the App Hub platform.

Author

app-developer-agent - Autonomous app development agent for the App Hub platform