# TimeTracker - Professional Time Tracking Application A comprehensive web-based time tracking application built with Flask, featuring project management, time tracking, invoicing, and analytics. ## ๐Ÿ“ธ Screenshots
Dashboard Projects Tasks Reports Task Management
## ๐ŸŒ Platform Support **Web Application (Primary)** - **Desktop**: Windows, macOS, Linux with modern web browsers - **Mobile**: Responsive design optimized for Android and iOS devices - **Tablets**: Full touch-friendly interface for iPad and Android tablets **Access Methods** - **Web Browser**: Chrome, Firefox, Safari, Edge (latest versions) - **Mobile Web**: Progressive Web App (PWA) capabilities - **API Access**: RESTful API for third-party integrations - **CLI Tools**: Command-line interface for administration and automation **Note**: This is a web-based application that runs in any modern browser. While not native mobile apps, the responsive design provides an excellent mobile experience across all devices. ## ๐Ÿ“Š Reporting Features ### Comprehensive Analytics Dashboard - **Real-time Statistics**: Live updates of current time tracking status - **Time Period Analysis**: Daily, weekly, and monthly hour summaries - **Project Performance**: Time breakdown by project with client information - **User Productivity**: Individual and team performance metrics - **Billable vs Non-billable**: Separate tracking for invoicing purposes ### Detailed Reports - **Project Reports**: Time analysis by project with user breakdowns - **User Reports**: Individual performance metrics and project allocation - **Summary Reports**: Key performance indicators and trends - **Custom Date Ranges**: Flexible reporting periods for analysis - **Export Capabilities**: CSV export with customizable delimiters ### Visual Analytics - **Progress Bars**: Visual representation of time allocation - **Statistics Cards**: Key metrics displayed prominently - **Trend Analysis**: Historical data visualization - **Mobile-Optimized Charts**: Responsive charts for all screen sizes ## โšก Automatic Time Tracking ### Smart Timer Features - **Idle Detection**: Automatic pause after configurable idle timeout (default: 30 minutes) - **Single Active Timer**: Option to allow only one active timer per user - **Auto-source Tracking**: Distinguishes between manual and automatic time entries - **Real-time Updates**: WebSocket-powered live timer updates ### Timer Management - **Start/Stop Controls**: Simple one-click timer management - **Project Association**: Automatic project linking for time entries - **Task Categorization**: Optional task-level time tracking - **Notes and Tags**: Rich metadata for time entries - **Duration Calculation**: Automatic time calculation and formatting ### Configuration Options - **Idle Timeout**: Customizable idle detection (5-120 minutes) - **Timer Behavior**: Single vs. multiple active timers - **Rounding Rules**: Configurable time rounding (1-minute increments) - **Timezone Support**: Full timezone awareness and conversion ## ๐Ÿข Client Management System ### Comprehensive Client Management - **Client Organization**: Create and manage client organizations with detailed information - **Contact Management**: Store contact person, email, phone, and address details - **Default Rate Setting**: Set standard hourly rates per client for automatic project population - **Status Management**: Active/inactive client status with archiving capabilities - **Project Relationships**: Clear view of all projects associated with each client ### Enhanced Project Creation - **Client Selection**: Dropdown selection instead of manual typing to prevent errors - **Automatic Rate Population**: Client default rates automatically fill project hourly rates - **Error Prevention**: Eliminates typos and duplicate client names - **Quick Setup**: Faster project creation with pre-filled client information ### Client Analytics - **Project Statistics**: Total and active project counts per client - **Time Tracking**: Total hours worked across all client projects - **Cost Estimation**: Estimated total cost based on billable hours and rates - **Performance Metrics**: Client-specific productivity and billing insights ## ๐Ÿ“ Data Standards & Import/Export ### Export Formats - **CSV Export**: Standard comma-separated values with configurable delimiters - **Data Fields**: Complete time entry information including: - User, Project, Client, Task details - Start/End times in ISO format - Duration in hours and formatted display - Notes, Tags, Source, Billable status - Creation and modification timestamps ### Data Structure - **Standardized Fields**: Consistent data format across all exports - **ISO 8601 Timestamps**: Standard datetime format for compatibility - **Configurable Delimiters**: Support for different regional CSV standards - **UTF-8 Encoding**: Full international character support ### Import Capabilities - **Database Schema**: PostgreSQL and SQLite support - **Migration Scripts**: Automated database schema updates - **Backup/Restore**: Database backup and restoration tools - **CLI Management**: Command-line database operations ### API Integration - **RESTful Endpoints**: Standard HTTP API for external access - **JSON Format**: Modern data exchange format - **Authentication**: Secure API access with user authentication - **Real-time Updates**: WebSocket support for live data synchronization ## ๐Ÿš€ Quick Start ### Prerequisites - Python 3.8+ - Docker (optional) - PostgreSQL (recommended) or SQLite ### Installation 1. Clone the repository 2. Install dependencies: `pip install -r requirements.txt` 3. Set up environment variables (see `env.example`) 4. Run the application: `python app.py` ## ๐Ÿ“ Project Structure The project has been organized for better maintainability: ``` TimeTracker/ โ”œโ”€โ”€ app/ # Main Flask application โ”‚ โ”œโ”€โ”€ models/ # Database models โ”‚ โ”œโ”€โ”€ routes/ # Route handlers โ”‚ โ”œโ”€โ”€ static/ # Static assets (CSS, JS, images) โ”‚ โ”œโ”€โ”€ templates/ # HTML templates โ”‚ โ””โ”€โ”€ utils/ # Utility functions โ”œโ”€โ”€ docs/ # Documentation and README files โ”œโ”€โ”€ docker-configs/ # Docker configurations and Dockerfiles โ”œโ”€โ”€ docker/ # Docker-related scripts and utilities โ”‚ โ”œโ”€โ”€ config/ # Configuration files (Caddyfile, supervisord) โ”‚ โ”œโ”€โ”€ fixes/ # Database and permission fix scripts โ”‚ โ”œโ”€โ”€ migrations/ # Database migration scripts โ”‚ โ”œโ”€โ”€ startup/ # Startup and initialization scripts โ”‚ โ””โ”€โ”€ tests/ # Docker environment test scripts โ”œโ”€โ”€ scripts/ # Deployment and utility scripts โ”œโ”€โ”€ tests/ # Application test suite โ”œโ”€โ”€ templates/ # Additional templates โ”œโ”€โ”€ assets/ # Project assets and screenshots โ””โ”€โ”€ logs/ # Application logs ``` ## ๐Ÿณ Docker Support Multiple Docker configurations are available in `docker-configs/`: - **Standard**: `docker-compose.yml` - Full application with all features - **Simple**: `docker-compose.simple.yml` - Minimal setup - **Python**: `docker-compose.python.yml` - Python-only environment - **WeasyPrint**: `docker-compose.weasyprint.yml` - With PDF generation - **Fixed**: `docker-compose.fixed.yml` - Resolved permission issues ### Enhanced Database Startup The application now includes an enhanced database startup procedure that automatically: - Creates all required tables with proper schema - Handles migrations and schema updates - Verifies database integrity before starting - Provides comprehensive error reporting See [Enhanced Database Startup Documentation](docs/ENHANCED_DATABASE_STARTUP.md) for detailed information. ### Version Management A comprehensive version management system provides flexible versioning: - **GitHub Releases** - Automatic versioning when creating releases - **Git Tags** - Manual version tagging for releases - **Build Numbers** - Automatic versioning for branch builds - **Local Tools** - Command-line version management scripts See [Version Management Documentation](docs/VERSION_MANAGEMENT.md) for detailed information. ## ๐Ÿ”ง Features - **Time Tracking**: Start/stop timer with project and task association - **Project Management**: Create and manage projects with client information - **Task Management**: Organize work into tasks and categories - **Invoicing**: Generate professional invoices from time entries - **Analytics**: Comprehensive reporting and time analysis - **User Management**: Multi-user support with role-based access - **Mobile Responsive**: Works on all devices - **CLI Tools**: Command-line interface for administration - **API Access**: RESTful API for integrations - **Real-time Updates**: WebSocket-powered live updates ## ๐Ÿ“š Documentation Detailed documentation is available in the `docs/` directory: - **API Documentation**: API endpoints and usage - **Feature Guides**: Detailed feature explanations - **Troubleshooting**: Common issues and solutions - **Deployment**: Setup and deployment instructions ## ๐Ÿš€ Deployment ### Docker Deployment ```bash # Use the appropriate docker-compose file docker-compose -f docker-configs/docker-compose.yml up -d ``` ### Manual Deployment ```bash # Install dependencies pip install -r requirements.txt # Set environment variables cp env.example .env # Edit .env with your configuration # Run the application python app.py ``` ## ๐Ÿงช Testing Run the test suite: ```bash python -m pytest tests/ ``` ## ๐Ÿค Contributing 1. Fork the repository 2. Create a feature branch 3. Make your changes 4. Add tests if applicable 5. Submit a pull request See `docs/CONTRIBUTING.md` for detailed guidelines. ## ๐Ÿ“„ License This project is licensed under the MIT License - see the `docs/LICENSE` file for details. ## ๐Ÿ†˜ Support - **Issues**: Report bugs and feature requests on GitHub - **Documentation**: Check the `docs/` directory - **Troubleshooting**: See `docs/SOLUTION_GUIDE.md` ## ๐Ÿ”„ Recent Updates - **Project Cleanup**: Reorganized project structure for better maintainability - **Docker Organization**: Consolidated Docker configurations and scripts - **Documentation**: Moved all documentation to dedicated `docs/` directory - **Script Organization**: Grouped utility scripts by purpose --- **Note**: This project has been cleaned up and reorganized. All files have been preserved and moved to appropriate directories for better organization and maintainability.