FocusTimer Plus 🍅

A multi-user, visually appealing focus timer web app (Pomodoro style), featuring Google OAuth login, per-user cloud data storage with Supabase, integrated task management, and session statistics dashboards.

Features

🔐 Authentication

• Google OAuth login via Supabase Auth
• Secure user authentication
• Per-user data isolation with Row Level Security (RLS)

⏱️ Focus Timer

• Pomodoro-style countdown (default 25 min focus/5 min break)
• Adjustable durations for work and break sessions
• Large, clear timer display with progress visualization
• Start, pause, reset controls
• Visual and sound feedback on session completion
• Automatic session logging

📝 Task Management

• Add, edit, mark done, and remove tasks
• Task list associated with logged-in user
• Persistent storage in Supabase
• Task filtering (all/active/completed)
• Task association with focus sessions

📊 Session Logging & Analytics

• Automatic session logging on completion
• Statistics dashboard with:
  • Daily/weekly/monthly session counts
  • Interactive charts and visualizations
  • Streak tracking (current and longest)
  • Task completion statistics
  • Record highs (most sessions per day/week/month)

🎨 Visually Appealing UI

• Modern, clean interface
• Light/dark theme support (via Streamlit config)
• Responsive design (works on desktop, tablet, mobile)
• Celebratory effects for milestones
• Smooth animations and transitions

Tech Stack

• Frontend/UI: Streamlit (Python)
• Authentication: Supabase Auth (Google provider)
• Backend/Database: Supabase (PostgreSQL with Row Level Security)
• Visualization: Plotly
• Data Storage: Supabase tables (tasks, sessions)

Prerequisites

• Python 3.8 or higher
• A Supabase account and project
• Google OAuth credentials configured in Supabase

Setup Instructions

1. Clone the Repository

git clone <repository-url>
cd FocusTimer

2. Install Dependencies

pip install -r requirements.txt

3. Supabase Setup

1. Create a new Supabase project at supabase.com

2. Enable Google OAuth in Supabase Dashboard:

   • Go to Authentication > Providers
   • Enable Google provider
   • Add your Google OAuth credentials (Client ID and Client Secret)
   • Set redirect URL to your app URL (e.g., http://localhost:8501 for local development)

3. Run the database schema:

   • Go to SQL Editor in Supabase Dashboard
   • Copy and paste the contents of sql/schema.sql
   • Execute the script to create tables and RLS policies

4. Get your Supabase credentials:

   • Go to Project Settings > API
   • Copy your Project URL and anon/public key

4. Environment Variables

Create a .env file in the project root (you can copy from .env.example):

SUPABASE_URL=your_supabase_project_url
SUPABASE_KEY=your_supabase_anon_key
REDIRECT_URL=http://localhost:8501

Note: For production deployment, update REDIRECT_URL to your production URL.

5. Run the Application

streamlit run app.py

The app will open in your browser at http://localhost:8501.

Database Schema

The application uses three main tables:

tasks

• id (UUID, Primary Key)
• user_id (UUID, Foreign Key to auth.users)
• text (TEXT)
• done (BOOLEAN)
• created_at (TIMESTAMP)
• completed_at (TIMESTAMP, nullable)

sessions

• id (UUID, Primary Key)
• user_id (UUID, Foreign Key to auth.users)
• session_type (TEXT: 'focus' or 'break')
• duration (INTEGER, seconds)
• timestamp (TIMESTAMP)
• task_id (UUID, Foreign Key to tasks, nullable)

Row Level Security (RLS)

All tables have RLS enabled, ensuring users can only access their own data. Policies are automatically enforced by Supabase.

Project Structure

FocusTimer/
├── app.py                 # Main Streamlit application
├── requirements.txt       # Python dependencies
├── .env.example          # Environment variables template
├── .streamlit/
│   └── config.toml       # Streamlit configuration
├── src/
│   ├── __init__.py
│   ├── auth.py           # Supabase authentication logic
│   ├── database.py       # Database operations (tasks, sessions)
│   ├── timer.py          # Pomodoro timer logic
│   ├── analytics.py      # Statistics and chart generation
│   └── utils.py          # Helper functions (audio, animations)
├── sql/
│   └── schema.sql        # Database schema and RLS policies
└── README.md             # This file

Usage

First Time Setup

1. Launch the app
2. Click "Sign in with Google"
3. Complete Google OAuth authentication
4. You'll be redirected back to the app, now logged in

Using the Timer

1. Go to the Timer tab
2. Adjust work/break durations in the sidebar (optional)
3. Select a task to work on (optional)
4. Click Start to begin a focus session
5. The timer will count down with visual progress
6. When the session completes, it's automatically logged
7. Switch to break mode or start another focus session

Managing Tasks

1. Go to the Tasks tab
2. Add new tasks using the form at the top
3. Check off tasks when completed
4. Delete tasks you no longer need
5. Filter tasks by status (All/Active/Completed)

Viewing Statistics

1. Go to the Statistics tab
2. Select a time period (Day/Week/Month)
3. View:
   • Session counts and focus time
   • Interactive charts
   • Streak information
   • Task completion rates
   • Record highs

Deployment

Streamlit Cloud

1. Push your code to GitHub
2. Go to share.streamlit.io
3. Connect your GitHub repository
4. Add environment variables in the Streamlit Cloud settings:
   • SUPABASE_URL
   • SUPABASE_KEY
   • REDIRECT_URL (your Streamlit Cloud app URL)
5. Deploy!

Other Platforms

The app can be deployed on any platform that supports Streamlit:

• Heroku
• AWS
• Google Cloud Platform
• Azure
• Docker containers

Make sure to:

• Set environment variables
• Update REDIRECT_URL in Supabase OAuth settings
• Ensure your database schema is set up

Troubleshooting

Authentication Issues

• Problem: "Error initiating OAuth"

  • Solution: Verify Google OAuth is enabled in Supabase and credentials are correct
  • Check that redirect URL matches your app URL

• Problem: User not authenticated after login

  • Solution: Check browser console for errors
  • Verify Supabase URL and key are correct in .env

Database Issues

• Problem: "Permission denied" errors

  • Solution: Verify RLS policies are set up correctly
  • Check that sql/schema.sql was executed completely

• Problem: Tables not found

  • Solution: Run sql/schema.sql in Supabase SQL Editor

Timer Issues

• Problem: Timer not updating automatically
  • Solution: The timer updates on page refresh. For continuous updates, interact with the page or wait for automatic refresh when running.

Security Notes

• All database access is protected by Row Level Security (RLS)
• User authentication is handled securely by Supabase
• Never commit .env file to version control
• Use environment variables for all sensitive data

Future Enhancements

Potential features for future versions:

• Custom Pomodoro workflows (long/short breaks)
• Task syncing with Google Tasks
• Push/browser notifications for session end
• Data export (CSV)
• Leaderboard for friendly competition
• Custom themes and personalization

License

This project is open source and available under the MIT License.

Support

For issues, questions, or contributions, please open an issue on the repository.

---

Happy Focusing! 🍅✨