WorkLog Pro

WorkLog Pro is a desktop-first work logging app designed to keep operating even when the network is unreliable or unavailable.
The core principle is simple: always save locally first, sync later.

It started as a monolithic prototype and was refactored into layered modules so the app is easier to reason about, debug, and maintain.

What it does

• Local authentication (bcrypt password hashing)
• Check-in / check-out and break tracking
• Hourly task logging with status tracking
• Screenshot capture and preview
• Background sync queue with retries and exponential backoff
• Offline-first persistence using SQLite
• Admin member management
• Desktop tray support (open, logout, exit)
• Debug and health-check scripts for fast diagnostics

Installation

Python source setup (Windows)

1. Create virtual environment:
   • python -m venv .venv
2. Activate:
   • .\.venv\Scripts\activate
3. Install dependencies:
   • python -m pip install --upgrade pip
   • pip install -r requirements.txt
4. Copy env template:
   • copy .env.example .env
5. Edit .env and set credentials (and Supabase values if cloud sync is used).
6. Update settings.json for non-secret app behavior (intervals, popup tuning, break window, etc.).
7. Run app:
   • python -m worklog_pro.main

Python source setup (macOS/Linux)

1. Create virtual environment:
   • python3 -m venv .venv
2. Activate:
   • source .venv/bin/activate
3. Install dependencies:
   • python -m pip install --upgrade pip
   • pip install -r requirements.txt
4. Copy .env.example to .env and update credential values.
5. Update settings.json for non-secret app settings.
6. Run app:
   • python -m worklog_pro.main

Executable users (.exe)

If you distribute the app as an executable:

1. Place .env in the same folder as the executable.
2. Run WorkLogPro.exe.
3. Verify worklog_pro.log is being created for diagnostics.

.env setup

Set only secrets/identity in .env:

• SUPABASE_URL
• SUPABASE_KEY
• INITIAL_ADMIN_USERNAME
• INITIAL_ADMIN_PASSWORD
• INITIAL_USER_USERNAME
• INITIAL_USER_PASSWORD

All non-secret runtime settings are in settings.json (committed defaults). Timezone is controlled there via "timezone" (default is now Asia/Kolkata).

First-use flow

1. Start app.
2. Login with seeded credentials from .env.
3. Check in.
4. Add hourly logs.
5. Capture screenshots.
6. Trigger sync manually or let scheduler run it.
7. Use tray menu for minimize/logout/exit.

Offline-first behavior

When internet is down:

• App remains usable.
• Records stay local with synced=False.
• Sync queue retries later using exponential backoff.
• UI remains responsive because sync work runs in background thread.

This avoids the common failure mode where desktop apps become unusable during network issues.

Architecture overview

Layer flow is enforced:

ui -> services -> repositories -> database -> models

core stays independent and reusable.

See ARCHITECTURE.md for details.

Folder structure

worklog_pro/
  config/
  core/
  models/
  database/
  repositories/
  services/
  ui/
  utils/
  main.py
scripts/
  app_check.py
  debug_cli.py
  build.py

Debug tools

• python scripts/app_check.py

  • Runs a health check (db, offline insert, sync callable, config, services)

• python scripts/debug_cli.py show-users

• python scripts/debug_cli.py show-sessions

• python scripts/debug_cli.py show-unsynced

• python scripts/debug_cli.py trigger-sync

• python scripts/debug_cli.py db-health

• python scripts/debug_cli.py check-config

Troubleshooting

• If the app logs but window does not reopen after close, check whether your OS tray area is hidden; the app stays in system tray by design.
• If sync is not working, run python scripts/debug_cli.py check-config first and verify SUPABASE_URL and SUPABASE_KEY.
• If something fails unexpectedly, inspect worklog_pro.log. Terminal output is intentionally short and human-readable.

Build instructions (PyInstaller)

Use:

python scripts/build.py

Output will be in dist/WorkLogPro.

Design Decisions

Why SQLite

SQLite is a practical fit for offline-first desktop software: no server process, fast local writes, and easy packaging.
Most importantly, it guarantees local persistence first.

Why Supabase

Supabase gives a straightforward REST surface without requiring a custom backend service for this stage.
That keeps deployment simpler while still supporting cloud sync.

Why PySide6

This app is desktop-first. PySide6 provides richer native desktop capabilities (timers, tray integration, thread signaling, screen capture integration points) than the original prototype stack.

Challenges Faced

• Designing sync behavior that is resilient without blocking UI
• Avoiding duplicate or out-of-order updates under retry conditions
• Preserving old feature parity while refactoring into clean layers
• Balancing local reliability with cloud eventual consistency

Failure Handling Philosophy

• Write local first, always
• Never crash due to network dependency
• Retry sync with backoff
• Mark records synced only after confirmed success
• Keep failures observable in logs

Key Learnings

• Architecture quality directly affects debug speed.
• Offline-first design must be intentional from schema to service layer.
• Threading boundaries and signal wiring matter as much as business logic in desktop apps.
• “Production-ready” is mostly about failure handling, not just feature count.

Known limitations

• Screenshot remote fallback preview is still basic.
• Full conflict resolution is currently last-write-wins and should evolve for richer collaborative scenarios.
• Packaging and runtime signing/notarization are environment-specific and not included yet.

Future improvements

• Add full conflict audit tooling and reconciliation reports
• Add migration framework for schema evolution
• Add richer diagnostics dashboard for sync queue state
• Add automated test suite for services and repositories