# Trackora — Full Technical, Architectural & Product Documentation

## Executive Summary
Trackora is an open-source, local-first desktop application designed for automated screen time analytics, application usage monitoring, and digital productivity wellbeing. It operates completely offline, storing all activity data in a local SQLite database without sending telemetry, user activity, or personal data to remote servers.

- **Product Name**: Trackora (Trackora Tracker / Trackora Screen Time)
- **Official Website**: https://trackora-tracker.vercel.app
- **Repository**: https://github.com/SamXop123/Trackora
- **License**: MIT License (Free & Open Source)
- **Supported Platforms**: Windows 10/11 (x64) and Linux GNOME Wayland (Fedora, Ubuntu, Arch, RHEL).

## Architectural Overview

### 1. Desktop Client GUI
- Built with Python 3.12 and PySide6 (Qt framework).
- Uses hardware-accelerated 2D canvas and vector rendering for interactive daily/weekly charts, activity timelines, and real-time dashboard cards.
- High-DPI scaling support across 100%, 125%, 150%, and 200% desktop scale factors.
- Dark theme inspired by modern developer tooling with low memory footprint (~45 MB RAM).

### 2. Background Daemon & Tracker Engine
- **Windows Subsystem**:
  - Implements native Win32 window APIs (`GetForegroundWindow`, `GetWindowThreadProcessId`, `QueryFullProcessImageNameW`).
  - Active window filtering ensures taskbars (`Shell_TrayWnd`) and minimized desktop wallpaper states are cleanly categorized.
  - Native `GetLastInputInfo` integration accurately detects physical mouse and keyboard idle times.
  - Power state and screen-lock awareness suspends tracking during laptop lid-close, sleep, lock screen (`LockApp.exe`, `LogonUI.exe`), and display-off states.
- **Linux Subsystem**:
  - Direct integration with GNOME Shell via DBus protocol for Wayland compositors.
  - Asynchronous window property resolution without X11 legacy dependencies.

### 3. Local Storage Engine (SQLite 3)
- 100% offline, zero-network architecture.
- Schema utilizes indexed timestamp ranges (`start_time`, `end_time`, `app_name`, `category`, `duration_seconds`).
- Single-pass epoch aggregation algorithm calculates total screen time, peak usage hours, and category ratios in under 5ms.
- Rolling automated local database backups protect user data integrity.

## Feature Matrix

| Feature | Trackora | Traditional Cloud Trackers |
| :--- | :--- | :--- |
| **Privacy & Telemetry** | 100% Offline (Zero Cloud) | Cloud-Synced, Remote Upload |
| **Data Ownership** | Local SQLite Database on your PC | Third-party cloud servers |
| **User Account** | None Required (Instant start) | Mandatory Email / SSO |
| **Resource Usage** | < 0.1% CPU, ~45MB RAM | Heavy browser / electron agents |
| **Platform Support** | Windows 10/11 & Linux GNOME | Usually Windows / macOS only |
| **Price & License** | 100% Free & Open Source (MIT) | Paid monthly subscription |

## Frequently Asked Questions (FAQ)

### Q: Why is Trackora called "Local-First"?
A: Local-First means that all computational logic and data storage occur exclusively on the user's personal computer. Trackora contains no network analytics SDKs, no tracking pixels, and no remote database sync.

### Q: How do I install Trackora on Windows?
A: Download `TrackoraSetup.exe` from https://trackora-tracker.vercel.app/TrackoraSetup.exe and execute the setup wizard. The application will configure optional startup launch and system tray integration.

### Q: How do I install Trackora on Linux?
A: On Fedora or RHEL distributions, download `trackora-2.2.1.rpm` and run:
```bash
sudo dnf install ./trackora-2.2.1.rpm
```
Alternatively, clone the repository from https://github.com/SamXop123/Trackora and execute `./install.sh`.

### Q: How does Trackora handle computer sleep and AFK?
A: Trackora incorporates hardware input activity monitoring. If there is no user input for 5 minutes, or if the screen locks/sleeps, the active session timer is retroactively closed at the point of inactivity, guaranteeing that inactive hours are never logged as active screen time.

## Key Endpoints & Downloads
- Official Homepage: https://trackora-tracker.vercel.app
- Windows Installer: https://trackora-tracker.vercel.app/TrackoraSetup.exe
- Linux RPM: https://trackora-tracker.vercel.app/trackora-2.2.1.rpm
- GitHub Source: https://github.com/SamXop123/Trackora
- AI Summary: https://trackora-tracker.vercel.app/llms.txt