TimeTracker/docs

TimeTracker Documentation

Welcome to the comprehensive TimeTracker documentation. Everything you need to install, configure, use, and contribute to TimeTracker.

---

📖 Quick Links

• 🚀 Getting Started Guide — Complete beginner tutorial (⭐ Start here!)
• Main README — Product overview and quick start
• Installation Guide — Step-by-step installation (Docker, SQLite)
• Uninstall / remove data — Stop Docker, remove volumes, disable or remove the AI helper
• Architecture — System overview and design
• Development Guide — Run locally, tests, releases
• API Quick Reference — REST API overview and examples
• Installation & Deployment — Get TimeTracker running
• Feature Guides — Learn what TimeTracker can do
• Troubleshooting — Solve common issues

---

🗺️ Documentation Map

docs/
├── 👤 User Documentation
│   ├── Getting Started
│   ├── Feature Guides
│   └── User Guides
│
├── 🔧 Administrator Documentation
│   ├── Configuration
│   ├── Deployment
│   ├── Security
│   └── Monitoring
│
├── 👨‍💻 Developer Documentation
│   ├── Contributing
│   ├── Architecture
│   ├── Development Setup
│   └── Testing
│
└── 📚 Reference
    ├── API Documentation
    ├── Implementation Notes
    └── Reports

---

👤 User Documentation

Getting Started

• 🚀 Getting Started Guide — Complete beginner tutorial (⭐ Start here!)
• Installation Guide — Step-by-step installation (root)
• Requirements — System requirements and dependencies

User Guides

• How to deploy: Docker Compose Setup · Docker Public Setup
• Quick Wins Implementation (Deployment Checklist) — Feature implementation status (not deployment steps)
• Quick Start Guide — Get started quickly
• Quick Start Local Development — Local development setup

Feature Documentation

• 📋 Complete Features Overview — Comprehensive documentation of all 130+ features (⭐ Complete reference!)
• Task Management — Complete task tracking system
• Client Management — Manage clients and relationships
• Invoice System — Generate and track invoices
• Calendar Features — Calendar view and bulk entry
• Expense Tracking — Track business expenses
• Payment Tracking — Track invoice payments
• Budget Alerts & Forecasting — Monitor project budgets
• Command Palette — Keyboard shortcuts and quick actions
• Bulk Time Entry — Create multiple time entries at once
• Time Entry Templates — Reusable time entry templates
• Weekly Time Goals — Set and track weekly hour targets
• Break Time for timers and manual entries — Pause timers (break time) and optional break field on manual entries (Issue #561)
• Time Rounding — Configurable time rounding
• Role-Based Permissions — Granular access control
• Subcontractor role and assigned clients — Restrict users to specific clients and projects

See features/ for additional feature documentation.

---

🔧 Administrator Documentation

Configuration

• Docker Compose Setup — Docker deployment guide
• Docker Public Setup — Production deployment
• Docker Startup Troubleshooting — Fix startup issues
• Email Configuration — Email setup
• OIDC Setup — OIDC/SSO authentication setup
• LDAP Setup — LDAP directory authentication (AUTH_METHOD=ldap or all)
• Support visibility — Hide donate/support UI with a purchased key; purchase key

Deployment

• Version Management — Managing versions
• Release Process — Release workflow
• Official Builds — Official build information

Security

• Security Documentation — Security guides and configuration
• CSRF Configuration — CSRF token setup
• CSRF Troubleshooting — Fix CSRF errors
• HTTPS Setup (Auto) — Automatic HTTPS
• HTTPS Setup (mkcert) — Manual HTTPS with mkcert
• See admin/security/ for all security-related documentation

Monitoring

• Monitoring Documentation — Monitoring and analytics setup
• See admin/monitoring/ for telemetry and analytics guides

📖 See admin/README.md for complete administrator documentation

---

👨‍💻 Developer Documentation

Terminology

Use consistent terms in code, API, and user-facing copy: time entry / time entries, client, project, task, invoice. See Product/UX Audit for full context and naming recommendations.

Getting Started

• Contributor Guide — Architecture, local dev, testing, adding routes/services/templates, versioning
• Contributing — How to contribute (root; quick overview)
• Contributing Guidelines (full) — Setup, standards, PR process
• Development Guide — Run locally, tests, releases
• Architecture — System overview and design
• Code of Conduct — Community standards
• Project Structure — Codebase organization and architecture

Development Setup

• Local Testing with SQLite — Quick local testing setup
• Local Development with Analytics — Development setup with analytics

Testing

• Testing Quick Reference — Testing overview
• Testing Coverage Guide — Coverage documentation
• See testing/ for additional testing documentation

CI/CD

• CI/CD Documentation — Continuous integration and deployment
  • Documentation — CI/CD overview
  • Quick Start — Get started with CI/CD
  • Implementation Summary — What was implemented
  • GitHub Actions Setup — Configure GitHub Actions

Technical Documentation

• Solution Guide — Technical solutions and patterns
• Frontend Quality Gates — Accessibility, performance, and modernization (web, desktop, mobile)
• Database Migrations — Database schema management
• Implementation Notes — Development notes and summaries

Product & Roadmap

• Competitive Analysis — Feature gap analysis and phase PRDs

📖 See development/README.md for complete developer documentation

---

📚 API Documentation

• API Quick Reference — Overview and quick examples
• REST API — Complete API reference with all endpoints (⭐ Full reference!)
• API Token Scopes — Understanding token permissions and scopes
• API Versioning — API versioning strategy
• API Enhancements — Recent API improvements

📖 See api/README.md for complete API documentation

Quick API Examples

Authentication:

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     https://your-domain.com/api/v1/projects

Create Time Entry:

curl -X POST -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"project_id": 1, "start_time": "2025-01-27T09:00:00", "end_time": "2025-01-27T17:00:00"}' \
     https://your-domain.com/api/v1/time-entries

See REST API Documentation for complete examples and endpoint details.

---

🚀 Installation & Deployment

Quick Start

1. Installation Guide — Step-by-step installation (root)
2. Getting Started Guide — Complete beginner tutorial
3. Docker Compose Setup — Recommended deployment method
4. Requirements — System requirements
5. Uninstall / remove data — Tear down containers, volumes, and optional AI (Ollama)

Database & Migrations

• Database Migrations — Database schema management with Flask-Migrate
• Migration Guide — Migrate existing databases
• Enhanced Database Startup — Automatic database initialization
• Database Startup Fix — Database connection troubleshooting
• Docker Connection Troubleshooting — Database connection in Docker

---

🛠️ Troubleshooting

Common Issues

• Uninstall / remove data — Stop Docker, remove volumes, disable AI helper and Ollama
• Docker Startup Troubleshooting — Docker won't start
• Database Connection Issues — Can't connect to database
• PDF Generation Issues — PDFs not generating
• Solution Guide — General problem solving
• Troubleshooting Transaction Error — Transaction issues

Quick Fixes

• Port conflicts: Change PORT=8081 in docker-compose command
• Database issues: Run docker-compose down -v && docker-compose up -d
• Permission errors: Check file ownership with chown -R $USER:$USER .
• Migration failures: See Database Migrations

---

📝 Additional Resources

Implementation Notes

Recent improvements and changes are documented in implementation-notes/:

• Layout & UX improvements
• Feature implementations
• Bug fixes and improvements
• Architecture changes

Reports & Analysis

Analysis reports and summaries are available in reports/:

• Bugfix summaries
• Audit reports
• Translation analysis

Feature-Specific Documentation

Detailed feature documentation is available in features/:

• Feature guides
• Quick start guides
• Implementation status

User Guides

Additional user guides are available in user-guides/:

• Step-by-step guides
• Tips and tricks
• Best practices

---

🔍 Documentation by Role

For New Users

1. Start with Main README for product overview
2. Follow Getting Started Guide for installation
3. Review Requirements to check system compatibility
4. Explore Feature Documentation to learn features

For Administrators

1. Follow Docker Compose Setup for deployment
2. Review Version Management for updates
3. Set up Email Configuration if needed
4. Configure OIDC/SSO for authentication
5. See admin/README.md for complete admin documentation

For Developers

1. Read Contributing Guidelines before making changes
2. Review Project Structure to understand codebase
3. Check Solution Guide for technical patterns
4. Use Local Testing with SQLite for development
5. See development/README.md for complete developer documentation

For Troubleshooting

1. Check Docker Startup Troubleshooting
2. Review Database Connection Issues
3. Consult Solution Guide for common problems
4. Check specific feature documentation if issue is feature-related

---

📁 Documentation Structure

docs/
├── README.md                          # This file - documentation index
├── GETTING_STARTED.md                 # Beginner tutorial
├── REQUIREMENTS.md                    # System requirements
├── FEATURES_COMPLETE.md               # Complete features list
│
├── guides/                            # User-facing guides
│   ├── DEPLOYMENT_GUIDE.md
│   ├── QUICK_START_GUIDE.md
│   └── ...
│
├── admin/                             # Administrator documentation
│   ├── configuration/                 # Configuration guides
│   ├── deployment/                    # Deployment guides
│   ├── security/                      # Security documentation
│   └── monitoring/                    # Monitoring & analytics
│
├── development/                       # Developer documentation
│   ├── CONTRIBUTING.md
│   ├── CODE_OF_CONDUCT.md
│   ├── PROJECT_STRUCTURE.md
│   └── ...
│
├── api/                               # API documentation
│   ├── REST_API.md
│   ├── API_TOKEN_SCOPES.md
│   └── ...
│
├── features/                          # Feature-specific guides
│   └── ...
│
├── implementation-notes/              # Development notes
│   └── ...
│
├── testing/                           # Testing documentation
│   └── ...
│
├── reports/                           # Reports & analysis
│   └── ...
│
├── user-guides/                       # Additional user guides
│   └── ...
│
└── cicd/                              # CI/CD documentation
    └── ...

---

📋 Documentation Audit

A summary of doc accuracy, outdated content, gaps, and contradictions is in DOCS_AUDIT.md. Use it when updating or reorganizing docs.

---

🤝 Contributing to Documentation

Found an error? Want to improve the docs?

1. Check the Contributing Guidelines
2. Make your changes to the relevant documentation file
3. Test that all links work correctly
4. Submit a pull request with a clear description

Good documentation helps everyone! 📚

---

💡 Tips for Using This Documentation

• Use the search function in your browser (Ctrl/Cmd + F) to find specific topics
• Follow links to related documentation for deeper understanding
• Start with Quick Links at the top if you're in a hurry
• Browse by role using the role-based sections above
• Check Implementation Notes for recent changes and improvements

---

Need help? Open an issue or check the troubleshooting section

Want to contribute? See our Contributing Guidelines

---

⬆ Back to Top