{"id":29219576,"url":"https://github.com/doumdi/project-time-tracker","last_synced_at":"2026-02-04T17:34:03.438Z","repository":{"id":301901410,"uuid":"1010623352","full_name":"doumdi/project-time-tracker","owner":"doumdi","description":"Simple time tracking per project, and presence detection with BLE devices","archived":false,"fork":false,"pushed_at":"2026-01-02T22:22:05.000Z","size":4245,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-05T07:53:44.086Z","etag":null,"topics":["ble-devices","copilot","electron","local","mcp","mpc-servers","portable","presence-detection","react","reporting","sqlite","time","tracking"],"latest_commit_sha":null,"homepage":"https://doumdi.github.io/project-time-tracker/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/doumdi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-06-29T13:20:46.000Z","updated_at":"2026-01-03T15:35:17.000Z","dependencies_parsed_at":"2025-08-23T20:16:56.929Z","dependency_job_id":"aeb069f9-6763-4c2e-8c0c-674493a4a38e","html_url":"https://github.com/doumdi/project-time-tracker","commit_stats":null,"previous_names":["doumdi/project-time-tracker"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/doumdi/project-time-tracker","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/doumdi%2Fproject-time-tracker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/doumdi%2Fproject-time-tracker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/doumdi%2Fproject-time-tracker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/doumdi%2Fproject-time-tracker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/doumdi","download_url":"https://codeload.github.com/doumdi/project-time-tracker/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/doumdi%2Fproject-time-tracker/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29091939,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-04T03:31:03.593Z","status":"ssl_error","status_checked_at":"2026-02-04T03:29:50.742Z","response_time":62,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ble-devices","copilot","electron","local","mcp","mpc-servers","portable","presence-detection","react","reporting","sqlite","time","tracking"],"created_at":"2025-07-03T02:05:45.851Z","updated_at":"2026-02-04T17:34:03.432Z","avatar_url":"https://github.com/doumdi.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Project Time Tracker\n\nA cross-platform desktop application for tracking time spent on engineering projects with modern UI and local database storage.\n\n## Available Implementations\n\nThis project is available in two implementations:\n\n### 1. **Electron/React Version** (Original)\n- Located in the root directory\n- Built with Electron, React, and SQLite\n- Web version available at [GitHub Pages](https://doumdi.github.io/project-time-tracker/)\n\n### 2. **Qt/C++/QML Version** (New)\n- Located in the `qt_app/` directory\n- Built with Qt 6, C++17, and QML\n- Native performance with smaller binary size\n- See [Qt App README](qt_app/README.md) for details\n\nBoth implementations share the same database schema and can work with the same data files.\n\n## 🌐 Try the Web Demo\n\nExperience Project Time Tracker directly in your browser with pre-populated demo data:\n\n**[Launch Web Demo →](https://doumdi.github.io/project-time-tracker/)**\n\nThe web demo runs entirely in your browser using an in-memory database. All data is temporary and stored locally in your browser - perfect for trying out the features without any installation!\n\n\u003e CAUTION : This project is completely generated by Copilot, use at your own risks.\n\nAuthor(s) :\n\n- Copilot for @doumdi\n\n## Screenshots\n\n\u003e **Note:** All screenshots below are taken in demo mode with pre-populated sample data. See the [Demo Mode](#demo-mode) section to run the app with demo data.\n\n### Time Tracker\n![Time Tracker Interface](docs/images/screenshot-time-tracker.png)\n\n### Charts\n![Charts and Analytics View](docs/images/screenshot-charts.png)\n\n### Parameters\n![Settings and Configuration](docs/images/screenshot-parameters.png)\n\n### Time Entries\n![Time Entries List View](docs/images/screenshot-time-entries.png)\n\n### Projects\n![Project Management Interface](docs/images/screenshot-projects.png)\n\n### Tasks\n![Task Management with Cumulated Time Tracking](docs/images/screenshot-tasks.png)\n\n### Reports\n![Reports and Analytics View](docs/images/screenshot-reports.png)\n\n### Office Presence\n![Office Presence Real-time Tracking](docs/images/screenshot-office-presence.png)\n\n### Configurable Presence Settings\n![Configurable Presence Settings](docs/images/screenshot-ble-settings.png)\n\n## Features\n\n- ✅ **Cross-platform** - Works on Windows, macOS, and Linux\n- ✅ **Project Management** - Add, edit, and delete projects with custom colors\n- ✅ **Project Budgets \u0026 Earnings Tracking** - Set project budgets, track earnings based on hourly rates, and monitor remaining budget/hours\n- ✅ **Multi-Currency Support** - Support for 20+ currencies with configurable hourly rates\n- ✅ **Task Management** - Create, edit, and delete tasks with due dates, project association, and time allocation\n- ✅ **Task Time Tracking** - Start/stop time tracking directly from tasks with automatic time entry creation\n- ✅ **Cumulated Time Display** - Visual progress tracking showing actual time spent vs allocated time per task\n- ✅ **Time Tracking** - Live timer with 5-minute precision rounding\n- ✅ **Quick Entry** - Add past time entries manually\n- ✅ **Office Presence Detection** - Automatic presence tracking using Bluetooth Low Energy (BLE) devices\n- ✅ **Efficient BLE Monitoring** - Minute-by-minute periodic scanning (30 seconds scan every 60 seconds) for better battery efficiency\n- ✅ **Real-time Device Detection** - Live status updates with flicker-free UI and detection counters\n- ✅ **Enhanced Real-time Device Discovery** - Immediate display of discovered BLE devices with visual \"NEW\" badges and pulse animations\n- ✅ **Configurable Presence Save Intervals** - User-configurable saving intervals (1-480 minutes, default 15 minutes)\n- ✅ **Automatic Session Management** - Creates/ends presence sessions based on device proximity (2-minute timeout)\n- ✅ **Real-time Detection Counters** - Live seconds counters for device detection and global session time\n- ✅ **Enhanced Debugging** - Comprehensive console logging with BLE SCAN and PRESENCE MONITOR prefixes\n- ✅ **MAC Address Highlighting** - Visual highlighting of Bluetooth MAC addresses in settings for easy identification\n- ✅ **Filtering \u0026 Search** - Filter time entries by project, date, and description\n- ✅ **Multiple Views** - Table view, calendar view (month/week/day), and charts\n- ✅ **Charts \u0026 Analytics** - Visual representations of time data\n- ✅ **Backup \u0026 Restore** - Export/import database to/from JSON files for easy backup and migration\n- ✅ **Local Database** - SQLite database that's easy to backup and move\n- ✅ **Internationalization** - English and French language support\n- ✅ **Modern UI** - Clean, responsive design with real-time updates\n\n## Technology Stack\n\n### Electron Version (Original)\n\n- **Electron** - Cross-platform desktop app framework\n- **React** - Modern UI library\n- **SQLite** - Local database for data storage\n- **Chart.js** - Charts and visualizations\n- **@stoprocent/noble** - Bluetooth Low Energy (BLE) device detection\n- **Webpack** - Build tool\n\n### Qt Version (New)\n\n- **Qt 6** - Cross-platform application framework (6.2+, 6.5+ recommended)\n- **C++17** - High-performance backend\n- **QML** - Declarative UI language\n- **Qt SQL** - Database module with SQLite support\n- **Qt Bluetooth** - BLE device detection\n- **Qt Charts** - Charts and visualizations\n- **CMake** - Build system\n\nSee [qt_app/README.md](qt_app/README.md) for Qt version installation and build instructions.\n\n## Installation \u0026 Setup\n\n1. **Clone the repository**\n   ```bash\n   git clone https://github.com/doumdi/project-time-tracker.git\n   cd project-time-tracker\n   ```\n\n2. **Install dependencies**\n   ```bash\n   npm install\n   ```\n\n3. **Development mode**\n   ```bash\n   # Terminal 1: Start the React dev server\n   npm start\n   \n   # Terminal 2: Start Electron in development mode\n   npm run electron-dev\n   ```\n\n4. **Build for production**\n   ```bash\n   # Build the React app\n   npm run build\n   \n   # Run the production version\n   npm run electron\n   ```\n\n5. **Package the app**\n   ```bash\n   # Create distributable packages\n   npm run dist\n   ```\n\n## Demo Mode\n\nTry the application with pre-populated demo data without affecting your real database!\n\n**Run in demo mode:**\n```bash\n# Build the app first\nnpm run build\n\n# Start in demo mode\nnpm run electron-demo\n```\n\nOr manually:\n```bash\nnpm run electron -- --demo_mode\n```\n\n**Demo mode features:**\n- ✅ **In-memory database** - No files created, all data is temporary\n- ✅ **Pre-populated data** - 10 projects, 280+ time entries, 10 tasks over 3 months\n- ✅ **Mock BLE devices** - 5 sample Bluetooth devices for testing presence tracking\n- ✅ **Realistic work patterns** - Natural work hours (no weekends), breaks, and sessions\n- ✅ **Perfect for screenshots** - Ideal for documentation and demonstrations\n\nThe window title will display \"(DEMO MODE)\" when running in demo mode. All data is lost when you close the application.\n\n## Usage\n\n### Getting Started\n\n1. **Create Projects**: Start by adding your projects in the \"Projects\" tab\n2. **Track Time**: Use the \"Time Tracker\" tab to start/stop timer or add quick entries\n3. **Configure BLE Devices**: (Optional) Set up Bluetooth devices for automatic office presence detection in Settings\n4. **Configure Presence Settings**: (Optional) Adjust presence save intervals (default 15 minutes) in Settings → Office Presence Detection\n5. **View Entries**: Check all your time entries in the \"Time Entries\" tab\n6. **Office Presence**: Monitor automatic presence detection with real-time counters in the \"Office Presence\" tab\n7. **Calendar View**: See your work schedule in the \"Calendar\" tab\n8. **Analytics**: View charts and statistics in the \"Charts\" tab\n\n### Time Tracking\n\n- **Live Timer**: Select a project and click \"Start Timer\" to begin tracking\n- **Quick Entry**: Toggle \"Quick Entry Mode\" to add past work manually\n- **5-minute Precision**: All durations are rounded to the nearest 5 minutes\n\n### Office Presence Detection\n\n- **Automatic Tracking**: Enable BLE device monitoring in Settings to track office presence automatically\n- **Efficient Scanning**: Minute-by-minute periodic scanning (30 seconds scan every 60 seconds) for optimal battery efficiency\n- **Real-time Monitoring**: Continuous scanning for registered Bluetooth devices (watches, phones, etc.) with live status updates\n- **Smart Sessions**: Automatically creates presence sessions when devices are detected, ends when devices are out of range (2-minute timeout)\n- **Configurable Save Intervals**: User-configurable presence save intervals (1-480 minutes, default 15 minutes) with automatic session rotation\n- **Minimum Session Time**: Only sessions 1 minute or longer are saved\n- **Live Status**: See real-time presence status with animated indicators and currently detected devices\n- **Real-time Counters**: Live seconds counters for each detected device and global session timer with human-readable formatting\n- **Enhanced Device Discovery**: Real-time BLE device discovery in settings with immediate display, visual \"NEW\" badges, pulse animations, and discovery timestamps\n- **Daily Summaries**: View cumulative presence time for each day\n- **Enhanced Debugging**: Comprehensive console logging with `[BLE SCAN]` and `[PRESENCE MONITOR]` prefixes for troubleshooting\n- **MAC Address Highlighting**: Visual highlighting of Bluetooth MAC addresses in BLE settings for easy device identification\n\n### BLE Device Management\n\n- **Real-time Device Discovery**: Click \"Start scan\" in BLE settings to immediately see discovered devices as they are found\n- **Visual Feedback**: Newly discovered devices show with animated green \"NEW\" badges and pulse effects\n- **Live Device Counter**: Real-time counter showing number of devices found during scanning\n- **Discovery Timestamps**: Each device shows when it was discovered for easy identification\n- **MAC Address Display**: Bluetooth MAC addresses are visually highlighted with gray backgrounds for easy debugging\n- **Device Clearing**: Discovered device list is automatically cleared before each new scan for fresh results\n- **Enhanced Reliability**: Improved event handling prevents duplicate listeners and ensures stable real-time updates\n\n### Data Management\n\n- **Database Location**: Your data is stored locally in SQLite database\n  - Windows: `%APPDATA%/project-time-tracker/timetracker.db`\n  - macOS: `~/Library/Application Support/project-time-tracker/timetracker.db`\n  - Linux: `~/.config/project-time-tracker/timetracker.db`\n\n- **Backup \u0026 Restore**: Use the built-in backup/restore feature in Settings with native file dialogs\n  - **Backup**: Export your entire database to a JSON file using native OS save dialog\n  - **Restore**: Import a previously exported JSON backup using native OS open dialog\n  - **Native File Dialogs**: Choose where to save backups and browse for restore files with familiar OS dialogs\n  - **Manual Backup**: You can also copy the database file directly for backup\n  \n![Backup \u0026 Restore Feature](docs/screenshot-backup-restore-with-dialogs.png)\n\n**Note**: Backup and restore work across different database versions, making it easy to migrate data between different versions of the application.\n\n## Development\n\n### Project Structure\n\n```\nsrc/\n├── app/                 # React application\n│   ├── App.js          # Main app component\n│   ├── index.js        # Entry point\n│   ├── index.html      # HTML template\n│   └── styles.css      # Global styles\n├── components/         # React components\n│   ├── ProjectManager.js\n│   ├── TimeTracker.js\n│   ├── TimeEntryList.js\n│   ├── CalendarView.js\n│   ├── ChartsView.js\n│   ├── OfficePresenceView.js    # Office presence tracking with real-time counters\n│   ├── BleDevicesView.js        # BLE device management with real-time discovery\n│   └── Settings.js              # Settings with configurable presence intervals\n├── contexts/            # React contexts\n│   ├── LanguageContext.js       # Internationalization support\n│   └── SettingsContext.js       # Application settings context\n├── database/           # Database operations\n│   └── db.js          # SQLite database interface\n├── translations/       # Localization files\n│   ├── en.json        # English translations\n│   └── fr.json        # French translations\n├── main.js            # Electron main process with BLE handlers\n└── preload.js         # Electron preload script with IPC bridge\n```\n\n### Database Schema\n\n**Projects Table**\n- `id` - Primary key\n- `name` - Project name (unique)\n- `description` - Optional description\n- `color` - Hex color code\n- `budget` - Project budget (decimal)\n- `start_date` - Project start date\n- `end_date` - Project end date\n- `created_at`, `updated_at` - Timestamps\n\n**Time Entries Table**\n- `id` - Primary key\n- `project_id` - Foreign key to projects\n- `description` - Optional description\n- `start_time` - ISO datetime string\n- `end_time` - ISO datetime string\n- `duration` - Duration in minutes\n- `created_at`, `updated_at` - Timestamps\n\n**BLE Devices Table** (v4+)\n- `id` - Primary key\n- `name` - Device display name\n- `address` - Bluetooth MAC address (unique)\n- `device_type` - Device type (watch, phone, etc.)\n- `is_active` - Whether device is enabled for monitoring\n- `created_at`, `updated_at` - Timestamps\n\n**Office Presence Table** (v4+)\n- `id` - Primary key\n- `date` - Presence date\n- `start_time` - Session start time (ISO datetime)\n- `end_time` - Session end time (ISO datetime)\n- `duration` - Session duration in minutes\n- `device_id` - Foreign key to BLE devices (optional)\n- `created_at`, `updated_at` - Timestamps\n\n## Building for Distribution\n\n### Desktop Applications\n\n#### Windows\n```bash\nnpm run dist\n# Creates: dist/Project Time Tracker Setup 1.0.4.exe\n```\n\n#### macOS\n```bash\nnpm run dist\n# Creates: dist/Project Time Tracker-1.0.4.dmg\n```\n\n#### Linux\n```bash\nnpm run dist\n# Creates: dist/Project Time Tracker-1.0.4.AppImage\n```\n\n### Web Version\n\nBuild the web version for deployment to static hosting (e.g., GitHub Pages):\n\n```bash\nnpm run build:web\n# Creates: dist-web/ directory with static files\n```\n\nThe web version:\n- Runs entirely in the browser using sql.js (in-memory SQLite)\n- Automatically starts in demo mode with sample data\n- All data is stored locally in the browser\n- No server-side components required\n- Perfect for demonstrations and trying out features\n\n## Troubleshooting\n\n### BLE (Bluetooth Low Energy) Issues\n\n**macOS:**\n- Ensure Bluetooth is enabled in System Preferences\n- Grant Bluetooth permission to the app when prompted\n- If installation fails with Python 3.13+, the app now uses `@stoprocent/noble` for better compatibility\n- Install Xcode command line tools if needed: `xcode-select --install`\n\n**Windows:**\n- Enable Bluetooth in Windows Settings\n- Ensure the app has Bluetooth permissions\n- Some USB Bluetooth adapters may not support BLE\n\n**Linux:**\n- Install required packages: `sudo apt-get install bluetooth bluez libbluetooth-dev libudev-dev`\n- Ensure your user is in the `bluetooth` group: `sudo usermod -a -G bluetooth $USER`\n- Restart after adding to the group\n\n**General:**\n- BLE features are optional - the app works fully without them\n- If BLE is not available, presence tracking will be disabled\n- Check that your Bluetooth adapter supports BLE (Bluetooth 4.0+)\n- **Enhanced Debugging**: Enable debug mode by opening Developer Tools (Ctrl+Shift+I / Cmd+Option+I) to see detailed BLE scanning logs with `[BLE SCAN]` and `[PRESENCE MONITOR]` prefixes\n- **Device Discovery Issues**: If devices aren't appearing in real-time, check the console for scan events and ensure Bluetooth permissions are granted\n- **MAC Address Identification**: Use the highlighted MAC addresses in BLE settings to identify and match your devices\n- **Performance**: The app uses efficient periodic scanning (30s every minute) to balance detection accuracy with battery life\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Test thoroughly\n5. Submit a pull request\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdoumdi%2Fproject-time-tracker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdoumdi%2Fproject-time-tracker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdoumdi%2Fproject-time-tracker/lists"}