Worklog Manager

A professional Python desktop application for precise work time tracking with automatic overtime calculation, break management, and comprehensive reporting capabilities. Built to ensure compliance with customizable work norms while providing detailed analytics and audit trails.

Screenshot

Professional time tracking interface with real-time session monitoring, break management, and productivity analytics

---

Table of Contents

• Worklog Manager
  • Screenshot
  • Table of Contents
  • Key Features
  • Installation
  • Usage
    • Daily Workflow
    • Key Functions
    • Display Reference
  • Technical Architecture
  • Configuration
  • Logging & Monitoring
  • Troubleshooting
  • Development Status
  • Documentation
  • Contributing
  • Support
  • License
  • Acknowledgments

Key Features

• Precise Time Tracking - Real-time session tracking with 1-second accuracy and automatic productive time calculation
• Break Management - Support for multiple break types (Lunch, Coffee, General) with automatic duration tracking
• Overtime Calculation - Automatic detection and tracking against configurable work norms (default: 7.5 hours)
• Action History & Revoke - Undo up to 5 recent actions with full state restoration and validation
• Export & Reporting - Generate professional reports in CSV, JSON, or PDF formats with productivity analytics
• Advanced UI - Light/Dark themes, system tray integration, customizable keyboard shortcuts, and color-coded status indicators
• Notification System - Configurable alerts for work reminders, break times, and overtime warnings
• Automated Backups - Scheduled database backups with retention policies for data safety
• Cross-Platform - Compatible with Windows, macOS, and Linux

Installation

Requirements: Python 3.7 or higher

Quick Start:

git clone <repository-url>
cd worklog-manager
python main.py

Note: Uses Python standard library only - no external dependencies required for core functionality.

Usage

Daily Workflow

1. Start Day - Begin time tracking for the current date
2. Stop/Continue - Pause for breaks (select type: Lunch, Coffee, or General) and resume work
3. End Day - Complete tracking and review summary (productive time, overtime, breaks)

Key Functions

Revoke Actions

• Undo up to the last 5 actions with full state restoration
• Review action history before confirming rollback
• Safe validation prevents invalid state transitions

Reset Day

• Completely clear today's data and start fresh
• ⚠️ Warning: Permanently deletes all today's data - requires double confirmation

Export Data

• Quick export options: Today (CSV), This Week (JSON), or Custom (CSV/JSON/PDF)
• Professional reports include productivity metrics, break analysis, and statistical trends
• Automated file naming and organized export directory

Display Reference

Time Indicators:

• Current Session • Total Work Time • Break Time • Productive Time • Remaining • Overtime

Color Codes:

• 🟢 Green: Meeting/exceeding targets
• 🟠 Orange: Approaching targets
• 🔴 Red: Overtime or critical status
• 🔵 Blue: Active session

Technical Architecture

Database: SQLite with three core tables

• work_sessions - Daily work summaries and status
• action_log - Complete audit trail with timestamps
• break_periods - Individual break tracking by type

Project Structure:

worklog-manager/
├── main.py              # Application entry point
├── config.ini           # Configuration settings
├── gui/                 # UI components and dialogs
├── core/                # Business logic and calculations
├── data/                # Database operations and models
├── exporters/           # CSV, JSON, PDF export modules
├── logs/                # Daily log files
├── exports/             # Generated reports
└── backups/             # Automated database backups

Configuration

Customize settings via config.ini:

• Work norm hours (default: 7.5)
• Theme and UI preferences
• Notification timing and alerts
• Backup retention policies
• Keyboard shortcuts

Logging & Monitoring

Daily logs stored in logs/ directory with format worklog_YYYYMMDD.log. Includes all actions, errors, and system events with configurable log levels.

Troubleshooting

Issue	Solution
Application won't start	Verify Python 3.7+ and file permissions
Database errors	Check disk space and write permissions
Timer not updating	Restart application or check system clock
Data not saving	Review logs and verify database file access

Debug: Check logs/worklog_YYYYMMDD.log for detailed error information.

Development Status

Current Version: 1.7.0 - All phases completed

• ✅ Phase 1: Core time tracking and break management
• ✅ Phase 2: Action history and revoke system
• ✅ Phase 3: Export and reporting (CSV/JSON/PDF)
• ✅ Phase 4: Advanced features (themes, notifications, system tray, keyboard shortcuts)

Documentation

Comprehensive documentation is available in the docs/ directory:

• Installation Guide - Detailed setup instructions for all platforms
• Quick Start Guide - Get started in 5 minutes
• Contributing Guide - How to contribute to the project
• Changelog - Version history and release notes
• Security Policy - Security considerations and reporting
• Code of Conduct - Community guidelines

Contributing

We welcome contributions! Please see our Contributing Guide for details on:

• How to report bugs
• How to suggest features
• Development setup
• Code style guidelines
• Pull request process

Support

• 📖 Documentation: Check the docs/ directory
• 🐛 Bug Reports: Open an issue
• 💡 Feature Requests: Submit a request
• 💬 Discussions: GitHub Discussions

License

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

Acknowledgments

See ACKNOWLEDGMENTS.md for credits and attributions.

---

Worklog Manager - Professional time tracking for productive teams

⭐ Star this repository if you find it helpful!

Report Bug · Request Feature · View Documentation