mirror/TimeTracker
1
0
Fork 0
mirror of https://github.com/DRYTRIX/TimeTracker.git synced 2026-05-09 05:50:06 -05:00
Code Issues Packages Projects Releases Wiki Activity
Files
main
TimeTracker/docs/mobile-desktop-apps/README.md
T
Dries Peeters eb2f5c6afa fix(apps): harden desktop and mobile server connectivity 
Desktop (Electron):
- Add two-step first-run wizard: test TimeTracker via GET /api/v1/info, then log in with API token
- Replace bogus token check with validateSession (users/me, fallback to timer/status for narrow scopes)
- Normalize base URLs; classify TLS/DNS/timeout errors; periodic 401 forces re-login
- Settings save/test use public + authenticated checks; prebuild/prestart and npm test

Server:
- Exempt /api/v1/info, /api/v1/health, and POST /api/v1/auth/login from HTML setup redirect
- Include setup_required on GET /api/v1/info for unfinished installs

Mobile (Flutter):
- Validate saved token against new server URL before persisting settings change
- Remove unused lib/core/config.dart; point BUILD_CONFIGURATION at app_config.dart

Docs: DESKTOP_SETTINGS, desktop README, mobile-desktop-apps README, REST_API /info
2026-04-16 19:59:20 +02:00

4.5 KiB
Raw Permalink Blame History

Mobile and Desktop Apps

This directory contains documentation for the TimeTracker mobile (Flutter) and desktop (Electron) applications.

Overview

The TimeTracker mobile and desktop apps provide native client applications that connect to the TimeTracker backend via REST API.

Mobile App (Flutter)

Located in mobile/ directory.

Features

  • Time tracking with start/stop timer
  • Project and task management
  • Time entries with calendar view
  • Offline support with automatic sync
  • Secure token-based authentication
  • Background timer updates

Setup

See mobile/README.md for setup instructions.

Build

  • Android: flutter build apk or flutter build appbundle
  • iOS: flutter build ios then archive in Xcode

Desktop App (Electron)

Located in desktop/ directory.

Features

  • Time tracking with system tray integration
  • Project and task management
  • Time entries viewing
  • Offline support
  • Secure token-based authentication
  • Global keyboard shortcuts (planned)

Setup

See desktop/README.md for setup instructions.

Build

  • Windows: npm run build:win
  • macOS: npm run build:mac
  • Linux: npm run build:linux

API Integration

Both apps use the TimeTracker REST API v1 (/api/v1/). See API Documentation for details.

Authentication

  1. Mobile app: Sign in with your web username and password; the server returns an API token (tt_…) which is stored securely. Changing the Server URL in Settings probes the new host with your saved token before persisting the change.
  2. Desktop app: Use the two-step sign-in wizard (test server, then API token) or Settings with an API token from Admin → Security & Access → API tokens (no username/password flow in the Electron app).
  3. Clients validate the server with GET /api/v1/info (and respect setup_required when the installation is not finished) and validate the token with authenticated API calls.

Required API Scopes

  • read:time_entries - View time entries and timer status (desktop session check fallback; mobile login token includes this)
  • write:time_entries - Create/update time entries and control timer
  • read:projects - View projects
  • read:tasks - View tasks
  • read:users - Optional on desktop tokens; preferred so GET /api/v1/users/me can be used for session verification

API Endpoints Used

  • GET /api/v1/info - API metadata (includes setup_required when the server install is not complete); used for discovery without auth
  • GET /api/v1/timer/status - Get active timer status
  • POST /api/v1/timer/start - Start timer
  • POST /api/v1/timer/stop - Stop timer
  • GET /api/v1/time-entries - List time entries
  • POST /api/v1/time-entries - Create time entry
  • PUT /api/v1/time-entries/{id} - Update time entry
  • DELETE /api/v1/time-entries/{id} - Delete time entry
  • GET /api/v1/projects - List projects
  • GET /api/v1/tasks - List tasks

Offline Support

Both apps support offline operation:

  1. Local Storage: Time entries, projects, and tasks are cached locally
  2. Sync Queue: Operations performed offline are queued for sync
  3. Automatic Sync: When connection is restored, queued operations are processed
  4. Conflict Resolution: Server data takes precedence on conflict

The mobile app sends an Idempotency-Key on queued POST /api/v1/time-entries creates so retries after connectivity drops do not duplicate entries. See REST API: Idempotent time entry creation.

Development

Mobile App Development

  1. Install Flutter SDK
  2. Run flutter pub get in mobile/ directory
  3. Run flutter run to start development

Desktop App Development

  1. Install Node.js 18+
  2. Run npm install in desktop/ directory
  3. Run npm run dev to start development

Distribution

Mobile Apps

  • Android: Generate signed APK/AAB and submit to Google Play Store
  • iOS: Archive and submit to Apple App Store (requires Apple Developer account)

Desktop Apps

  • Windows: NSIS installer created in dist/ directory
  • macOS: DMG installer (requires code signing for distribution)
  • Linux: AppImage and .deb packages

Version Management

App versions should align with the backend version (see setup.py for current version). Update version numbers in:

  • Mobile: mobile/pubspec.yaml
  • Desktop: desktop/package.json
  • Backend: setup.py

Support

For issues or questions:

  1. Check the main project README
  2. Review API documentation
  3. Check app-specific README files
  4. Open an issue on GitHub
Reference in New Issue View Git Blame Copy Permalink