TimeTracker

<div align="center">

Professional Time Tracking & Project Management for Teams

Track time. Manage projects. Generate invoices. All in one place.

🆕 What's New • 🚀 Quick Start • ✨ Features • 📸 Screenshots • 📖 Getting Started • 📚 Documentation • 📋 Changelog • 🐳 Deploy

---

</div>

🎯 What is TimeTracker?

TimeTracker is a self-hosted, web-based time tracking application designed for freelancers, teams, and businesses who need professional time management with complete control over their data.

Perfect for:

• 💼 Freelancers tracking billable hours across multiple clients
• 👥 Small Teams managing projects and tracking productivity
• 🏢 Agencies needing detailed reporting and client billing
• 🔒 Privacy-focused organizations wanting self-hosted solutions

You can support the project and purchase a key to hide donate prompts in your instance.

---

🛠️ Technology Stack

TimeTracker is built with modern, reliable technologies:

Backend

• Python 3.11+ — Core programming language
• Flask 3.0.0 — Web framework
• SQLAlchemy 2.0.23 — ORM and database toolkit
• Flask-SocketIO 5.3.6 — WebSocket support for real-time updates
• Flask-Migrate 4.0.5 — Database migrations
• Flask-Babel 4.0.0 — Internationalization (i18n)

Frontend

• HTML5, JavaScript (ES6+) — Modern web standards
• Tailwind CSS 3.3.5 — Utility-first CSS framework
• Chart.js — Interactive data visualization
• Command Palette (cmdk) — Keyboard-driven navigation
• Framer Motion — Smooth animations and transitions

Database

• PostgreSQL — Production database (recommended)
• SQLite — Development and testing database

Deployment & Infrastructure

• Docker & Docker Compose — Containerization and orchestration
• Nginx — Reverse proxy and HTTPS termination
• Gunicorn — Production WSGI server
• Eventlet — Async networking library

Key Libraries & Tools

• WeasyPrint — PDF generation for invoices
• Flask-WTF — Form handling and CSRF protection
• Authlib — OAuth/OIDC authentication
• APScheduler — Background task scheduling
• Prometheus Client — Metrics collection
• Sentry SDK — Error monitoring (optional)
• PostHog — Product analytics (optional)

Development & Testing

• pytest — Testing framework
• black — Code formatting
• flake8 — Linting
• coverage — Test coverage analysis

📖 Documentation: Architecture overview · Project Structure · UI Guidelines

---

🖥️ UI overview

The web app uses a single main layout with a sidebar and top header. Content is centered with a max width for readability. Getting around: Dashboard — overview, today’s stats, and the main Timer widget (start/stop, quick start, repeat last). Timer and Time entries are first-class in the sidebar for fast access. Time entries is the place to filter, review, and export all logged time. Reports (time, project, finance) are available from the sidebar (top-level Reports link or Finance & Expenses → Reports for Report Builder, Saved Views, Scheduled Reports), and from the bottom bar on mobile. Projects, Finance, and Settings are available from the sidebar and navigation. For design and component conventions, see UI Guidelines.

---

🆕 What's New

TimeTracker has been continuously enhanced with powerful new features! Here's what's been added recently:

📋 For complete release history, see CHANGELOG.md

Current version is defined in setup.py (single source of truth). See CHANGELOG.md for versioned release history.

• 📱 Native Mobile & Desktop Apps — Flutter mobile app (iOS/Android) and Electron desktop app with time tracking, offline support, and API integration (Build Guide, Docs)
• 📋 Project Analysis & Documentation — Comprehensive project analysis and documentation updates
• 🔧 Version Consistency — Fixed version inconsistencies across documentation files

See CHANGELOG.md for all release notes and version history.

🎯 Major Feature Additions

🧾 Complete Invoicing System

• Professional Invoice Generation — Convert tracked time directly into polished invoices
• PDF Export — Generate beautiful, branded PDF invoices with your company logo
• Multi-Currency Support — Invoice clients in their preferred currency
• Tax Calculations — Automatic tax computation with configurable rates
• Invoice Status Tracking — Monitor draft, sent, paid, and overdue invoices
• Recurring Invoices — Automate regular billing cycles
• Email Integration — Send invoices directly to clients from the platform
• Peppol & ZugFerd e-Invoicing (EN 16931) — Send invoices via Peppol (generic HTTP AP or native SML/SMP + AS4); embed EN 16931 XML in invoice PDFs (ZugFerd/Factur-X); optional PDF/A-3 normalization and veraPDF validation (setup guide)

📋 Advanced Task Management

• Full Task System — Create, assign, and track tasks with priorities and due dates
• Kanban Board — Visual drag-and-drop task management with customizable columns
• Task Comments — Collaborate with threaded comments on tasks
• Task Activity Tracking — See complete history of task changes and updates
• Bulk Task Operations — Manage multiple tasks at once

💼 Complete CRM Suite 🆕

• Multiple Contacts per Client — Manage unlimited contacts for each client
• Sales Pipeline — Visual Kanban-style pipeline for tracking deals and opportunities
• Deal Management — Track deal value, probability, stages, and close dates
• Lead Management — Capture, score, and convert leads into clients or deals
• Communication History — Track all emails, calls, meetings, and notes with contacts
• Deal & Lead Activities — Complete activity tracking for sales processes

⏱️ Enhanced Time Tracking

• Calendar View — Visual calendar interface for viewing and managing time entries
• Bulk Time Entry — Create multiple time entries for consecutive days with weekend skipping
• Time Entry Templates — Save and reuse common time entries for faster logging
• Real-time Updates — See live timer updates across all devices via WebSocket

💰 Financial Management

• Expense Tracking — Track business expenses with receipts, categories, and approval workflows
• Payment Tracking — Monitor invoice payments with multiple payment methods
• Billable Expenses — Mark expenses as billable and automatically include in invoices
• Reimbursement Management — Handle expense approvals and reimbursements

🔐 Enterprise Security & Access

• Role-Based Access Control (RBAC) — Granular permissions system with custom roles
• OIDC/SSO Authentication — Enterprise authentication support (Azure AD, Authelia, etc.)
• API Tokens — Generate secure tokens for API access and integrations
• Audit Logs — Track all system activity and user actions

⌨️ Productivity Power-Ups

• Command Palette — Keyboard-driven navigation (press ? to open)
• Keyboard Shortcuts — 50+ shortcuts for lightning-fast navigation
• Quick Search — Fast search across projects, tasks, clients, and more (Ctrl+K)
• Saved Filters — Save frequently used report filters for instant access

✏️ Content & Formatting

• Markdown Support — Rich text formatting in project and task descriptions
• Enhanced UI Components — Modern, accessible interface components
• Toast Notifications — Beautiful in-app notifications for actions and updates

🎨 Modern UX & Layout Enhancements 🆕

• Enterprise-Grade Tables — Sortable columns, bulk actions, inline editing, and CSV export
• Enhanced Search — Instant search with autocomplete, recent searches, and categorized results (Ctrl+K)
• Data Visualization — Interactive charts with Chart.js (6 chart types, responsive, exportable)
• Progressive Web App (PWA) — Install as mobile app, offline support, background sync
• Accessibility Excellence — WCAG 2.1 AA compliant, keyboard navigation, screen reader support
• Interactive Onboarding — Step-by-step product tours for new users
• Advanced Forms — Auto-save, form state persistence, inline validation, smart defaults
• Design System — Unified component library with 20+ reusable UI components
• Loading States — Skeleton components and loading indicators throughout
• Enhanced Empty States — Beautiful, actionable empty states with guidance

🏗️ Architecture & Performance Improvements 🆕

• Service Layer Migration — Routes migrated to service layer pattern for better maintainability
• Query Optimization — Fixed N+1 query problems, reduced database queries by 80-90%
• Environment Validation — Comprehensive startup validation with helpful error messages
• Base CRUD Service — Reusable service classes reducing code duplication
• API Token Security — Enhanced token management with rotation, expiration, and scoping

---

✨ Features

TimeTracker includes 130+ features across 13 major categories. See the Complete Features Documentation for a comprehensive overview.

📖 Quick Links:

• 📋 Complete Features List — All features in detail
• ⏱️ Time Tracking — Timer and time entry features
• 📊 Project Management — Projects, tasks, and organization