TimeTrack

TimeTrack is a comprehensive web-based time tracking application built with Flask that provides enterprise-level time management capabilities for teams and organizations. The application features multi-tenancy support, role-based access control, project management, team collaboration, billing/invoicing, and secure authentication with 2FA and password reset functionality. It includes a Progressive Web App (PWA) interface with mobile-optimized features.

Features

Core Time Tracking

• Real-time Time Tracking: Clock in/out with live timer functionality
• Project Time Logging: Track time spent on specific projects with project codes
• Break Management: Configurable mandatory and additional break tracking
• Time Entry Management: Edit, delete, and view time entries with complete history
• Automatic Calculations: Duration calculations for work hours and breaks

User Management & Security

• Two-Factor Authentication (2FA): TOTP-based authentication with QR codes
• Password Reset: Secure email-based password recovery (1-hour token expiry)
• Role-Based Access Control: System Admin, Admin, Supervisor, Team Leader, and Team Member roles
• Multi-Tenancy: Complete data isolation between companies
• User Administration: Create, edit, block/unblock users with email verification
• Profile Management: Update email, password, avatar, and personal settings
• Company Invitations: Invite users to join your company via email

Team & Project Management

• Team Management: Create teams, assign members, and track team hours
• Project Management: Create projects with codes, categories, billing types (hourly/daily/fixed)
• Sprint Management: Agile sprint planning and tracking
• Task Management: Create and manage tasks with subtasks and dependencies
• Notes System: Create, organize, and share notes with folder structure
• Team Hours Tracking: View team member working hours with date filtering
• Project Assignment: Flexible project-team assignments and access control

Export & Reporting

• Multiple Export Formats: CSV, Excel, and PDF export capabilities
• Individual Time Export: Personal time entries with date range selection
• Team Hours Export: Export team member hours with filtering options
• Invoice Generation: Create and export invoices with tax configurations
• Analytics Dashboard: Visual analytics with charts and statistics
• Quick Export Options: Today, week, month, or all-time data exports

Administrative Features

• Company Management: Multi-company support with separate settings
• Admin Dashboard: System overview with user, team, and activity statistics
• System Settings: Configure registration, email verification, tracking scripts
• Work Configuration: Set work hours, break rules, and rounding preferences
• Tax Configuration: Country-specific tax rates for invoicing
• Branding: Custom logos, colors, and application naming
• User Administration: Complete user lifecycle management
• Team & Project Administration: Full CRUD operations for teams and projects
• System Admin Tools: Multi-company oversight and system health monitoring

Tech Stack

• Backend: Flask 2.0.1 with SQLAlchemy ORM
• Database: PostgreSQL (production)
• Migrations: Flask-Migrate (Alembic-based) with custom helpers
• Authentication: Session-based with 2FA and password reset via Flask-Mail
• Frontend: Server-side Jinja2 templates with vanilla JavaScript
• Mobile: Progressive Web App (PWA) with mobile-optimized UI
• Export: Pandas for CSV/Excel, ReportLab for PDF generation
• Containerization: Docker and Docker Compose for easy deployment
• Dependencies: See requirements.txt for complete dependency list

Installation

Prerequisites

• Python 3.9+
• PostgreSQL 15+ (for production)
• Docker & Docker Compose (recommended)

Quick Start with Docker (Recommended)

# Clone the repository
git clone https://github.com/nullmedium/TimeTrack.git
cd TimeTrack

# Copy and configure environment variables
cp .env.example .env
# Edit .env with your settings

# Start the application
docker-compose up -d

# Access at http://localhost:5000

Local Development Setup

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Set environment variables
export DATABASE_URL="postgresql://user:pass@localhost/timetrack"
export SECRET_KEY="your-secret-key"
export MAIL_SERVER="smtp.example.com"
# ... other environment variables

# Run migrations
python create_migration.py "Initial setup"
python apply_migration.py

# Run the application
python app.py

First-Time Setup

1. Start the Application: The database is automatically created and initialized on first startup
2. Admin Account: An initial admin user is created automatically with username admin and password admin
3. Change Default Password: IMPORTANT: Change the default admin password immediately after first login
4. System Configuration: Access Admin Dashboard to configure system settings
5. Team Setup: Create teams and assign team leaders
6. Project Creation: Set up projects with codes and team assignments
7. User Management: Add users and assign appropriate roles

Database Migrations

Flask-Migrate System: The application uses Flask-Migrate (Alembic-based) for database version control.

# Create a new migration
python create_migration.py "Description of changes"

# Apply migrations
python apply_migration.py

# Check migration status
python check_migration_state.py

# For Docker environments
docker exec timetrack-timetrack-1 python create_migration.py "Description"
docker exec timetrack-timetrack-1 python apply_migration.py

The migration system handles:

• Automatic schema updates on container startup
• PostgreSQL-specific features (enums, constraints)
• Safe rollback capabilities
• Multi-tenancy data isolation
• Preservation of existing data during schema changes

Configuration

Environment Variables

# Database
DATABASE_URL=postgresql://user:password@host:5432/dbname

# Flask
SECRET_KEY=your-secret-key-here
FLASK_ENV=development  # or production

# Email (required for invitations and password reset)
MAIL_SERVER=smtp.example.com
MAIL_PORT=587
MAIL_USE_TLS=true
MAIL_USERNAME=your-email@example.com
MAIL_PASSWORD=your-password

# Optional
FORCE_HTTPS=true  # Force HTTPS in production
TRUST_PROXY_HEADERS=true  # When behind reverse proxy

Application Settings

• Company Settings: Work hours, break requirements, time rounding
• User Preferences: Date/time formats, timezone, UI preferences
• System Settings: Registration, email verification, tracking scripts
• Branding: Custom logos, colors, and naming

Usage

For Regular Users

1. Register/Login: Create account or log in with existing credentials
2. Setup 2FA: Optionally enable two-factor authentication for enhanced security
3. Clock In/Out: Use the timer interface to track work hours
4. Manage Breaks: Record and track break periods
5. View History: Access complete time entry history with filtering
6. Export Data: Download time entries in CSV or Excel format

For Team Leaders

1. Manage Team Members: View team member status and activity
2. Track Team Hours: Monitor team working hours with date filtering
3. Export Team Data: Generate team hour reports

For Supervisors/Admins

1. User Management: Create, edit, and manage user accounts
2. Team Administration: Create teams and assign members
3. Project Management: Set up projects and assign to teams
4. System Configuration: Configure global settings and permissions
5. Analytics: View system-wide statistics and activity

Security Features

• Two-Factor Authentication: TOTP-based 2FA with QR code setup
• Password Reset: Secure email-based recovery with time-limited tokens
• Role-Based Access Control: Five distinct user roles with granular permissions
• Multi-Tenancy: Complete data isolation between companies
• Session Management: Secure sessions with configurable lifetime
• Email Verification: Optional email verification for new accounts
• Password Strength: Enforced password complexity requirements
• Security Headers: HSTS, CSP, X-Frame-Options, and more
• Input Validation: Comprehensive server-side validation
• CSRF Protection: Built-in Flask CSRF protection

Features for Mobile Users

• Progressive Web App: Install TimeTrack as an app on mobile devices
• Mobile Navigation: Bottom navigation bar and hamburger menu
• Touch Optimization: 44px minimum touch targets throughout
• Responsive Tables: Automatic card view on small screens
• Mobile Gestures: Swipe navigation and pull-to-refresh
• Date/Time Pickers: Mobile-friendly pickers respecting user preferences
• Offline Support: Basic offline functionality with service workers
• Performance: Lazy loading and optimized for mobile networks

Project Structure

TimeTrack/
├── app.py                 # Main Flask application
├── models/               # Database models organized by domain
│   ├── user.py          # User, Role, UserPreferences
│   ├── company.py       # Company, CompanySettings
│   ├── project.py       # Project, ProjectCategory
│   ├── time_entry.py    # TimeEntry model
│   └── ...              # Other domain models
├── routes/              # Blueprint-based route handlers
│   ├── auth.py         # Authentication routes
│   ├── projects.py     # Project management
│   ├── teams.py        # Team management
│   └── ...             # Other route modules
├── templates/           # Jinja2 templates
├── static/             # CSS, JS, images
│   ├── css/           # Stylesheets including mobile
│   ├── js/            # JavaScript including PWA support
│   └── manifest.json  # PWA manifest
├── migrations/         # Flask-Migrate/Alembic migrations
├── docker-compose.yml  # Docker configuration
└── requirements.txt    # Python dependencies

API Endpoints

Key application routes organized by function:

• / - Home dashboard
• /login, /logout, /register - Authentication
• /forgot_password, /reset_password/<token> - Password recovery
• /time-tracking - Main time tracking interface
• /projects/* - Project management
• /teams/* - Team management
• /tasks/* - Task and sprint management
• /notes/* - Notes system
• /invoices/* - Billing and invoicing
• /export/* - Data export functionality
• /admin/* - Administrative functions
• /system-admin/* - System administration (multi-company)

Deployment

Production Deployment with Docker

# Clone and configure
git clone https://github.com/nullmedium/TimeTrack.git
cd TimeTrack
cp .env.example .env
# Edit .env with production values

# Build and start
docker-compose -f docker-compose.yml up -d

# View logs
docker-compose logs -f

# Backup database
docker exec timetrack-db-1 pg_dump -U timetrack timetrack > backup.sql

Reverse Proxy Configuration (Nginx)

server {
    listen 80;
    server_name timetrack.example.com;
    
    location / {
        proxy_pass http://localhost:5000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Troubleshooting

Common Issues

1. Migration Errors

   • Check current state: python check_migration_state.py
   • View migration history: flask db history
   • Fix revision conflicts in alembic_version table

2. Docker Issues

   • Container not starting: docker logs timetrack-timetrack-1
   • Database connection: Ensure PostgreSQL is healthy
   • Permission errors: Check volume permissions

3. Email Not Sending

   • Verify MAIL_* environment variables
   • Check firewall rules for SMTP port
   • Enable "less secure apps" if using Gmail

4. 2FA Issues

   • Ensure system time is synchronized
   • QR code not scanning: Check for firewall blocking images

Contributing

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

Development Guidelines

• Follow PEP 8 for Python code
• Write tests for new features
• Update documentation as needed
• Ensure migrations are reversible
• Test on both PostgreSQL and SQLite

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Flask community for the excellent framework
• Contributors and testers
• Open source projects that made this possible