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

Clone the repository
Install dependencies: pip install -r requirements.txt
Set up environment variables (see env.example)
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/                # 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-compose.yml      # Local development setup
├── docker-compose.remote.yml      # Production deployment
├── docker-compose.remote-dev.yml  # Development deployment
└── Dockerfile              # Application container definition

🐳 Docker Support

Multiple Docker configurations are available for different deployment scenarios:

Local Development

docker-compose.yml - Standard local development setup with all features
- Builds from local source code
- Includes optional Caddy reverse proxy for TLS
- Suitable for development and testing

Remote Deployment

docker-compose.remote.yml - Production deployment using GitHub Container Registry
- Uses pre-built ghcr.io/drytrix/timetracker:latest image
- Secure cookie settings enabled
- Optimized for production environments
docker-compose.remote-dev.yml - Development deployment using GitHub Container Registry
- Uses pre-built ghcr.io/drytrix/timetracker:development image
- Secure cookie settings enabled
- Suitable for testing pre-release versions

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 for detailed information.

Docker Compose Usage

Quick Start with Local Development

# Clone the repository
git clone https://github.com/drytrix/TimeTracker.git
cd TimeTracker

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

# Start the application
docker-compose up -d

# Access the application at http://localhost:8080

Production Deployment with Remote Images

# Use production-ready images from GitHub Container Registry
docker-compose -f docker-compose.remote.yml up -d

# Or use development version for testing
docker-compose -f docker-compose.remote-dev.yml up -d

Development with TLS Support

# Start with Caddy reverse proxy for HTTPS
docker-compose --profile tls up -d

# Access via HTTPS at https://localhost

Environment Configuration

All docker-compose files support the following environment variables (set in .env file):

TZ - Timezone (default: Europe/Brussels)
CURRENCY - Currency symbol (default: EUR)
ROUNDING_MINUTES - Time rounding in minutes (default: 1)
SINGLE_ACTIVE_TIMER - Allow only one active timer per user (default: true)
ALLOW_SELF_REGISTER - Allow user self-registration (default: true)
IDLE_TIMEOUT_MINUTES - Auto-pause timer after idle time (default: 30)
ADMIN_USERNAMES - Comma-separated list of admin usernames (default: admin)
SECRET_KEY - Flask secret key (change this in production!)
SESSION_COOKIE_SECURE - Secure session cookies (default: false for local, true for remote)
REMEMBER_COOKIE_SECURE - Secure remember cookies (default: false for local, true for remote)

Database Configuration

POSTGRES_DB - Database name (default: timetracker)
POSTGRES_USER - Database user (default: timetracker)
POSTGRES_PASSWORD - Database password (default: timetracker)

Useful Commands

# View logs
docker-compose logs -f app

# Stop all services
docker-compose down

# Stop and remove volumes (⚠️ deletes all data)
docker-compose down -v

# Rebuild and restart
docker-compose up -d --build

# Check service status
docker-compose ps

# Access database directly
docker-compose exec db psql -U timetracker -d timetracker

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 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

# Local development
docker-compose up -d

# Production with remote images
docker-compose -f docker-compose.remote.yml up -d

# Development with remote images
docker-compose -f docker-compose.remote-dev.yml up -d

Manual Deployment

# 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:

python -m pytest tests/

🤝 Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
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.

Languages

Python 54.7%

HTML 34.3%

JavaScript 6.6%

Shell 1.6%

Dart 1.1%

Other 1.6%