# activitywatch/aw-qt architecture

> Architecture diagram of the GitHub repository activitywatch/aw-qt, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/activitywatch/aw-qt
- Repository: https://github.com/activitywatch/aw-qt

## Overview

##### Project type and purpose
- Its primary job is to start, stop, and monitor the aw-server and its watchers, and provide a system tray UI for user control and status feedback.

##### File structure
- aw_qt/
– __main__.py, main.py: application entry points
– config.py: configuration loader/parser
– manager.py: logic to spawn, monitor, and control aw-server and watchers
- scripts/config-autostart.sh: system/user autostart helper
- Makefile, aw-qt.spec, pyproject.toml: build, packaging, dependencies
- .github/workflows: CI for build and code analysis
- tests/integration_tests.py: end‐to‐end testing

##### README for additional insights
- Directs to Makefile for build instructions—so packaging and distribution are core concerns.

##### Main components and their interactions
a. User Interface (UI)
– Settings Dialog (if any, via config.py)
b. Service Manager
– Process control: start/stop aw-server and watcher subprocesses (manager.py)
– Health checks and restart logic
c. Configuration
– Reads/writes config file (config.py)
– Autostart script integration (scripts/config-autostart.sh)
d. External Services
– aw-server (HTTP/REST API for data collection)
– Watchers (processes sending events to aw-server)
e. Packaging & Deployment
– .desktop file for desktop environments (resources/)
– spec file for RPM (aw-qt.spec)
– Makefile/pyproject.toml for build, versioning, and dependency management

##### Relationships and data flows
- UI → Service Manager: user clicks in tray menu to start/stop services
- Service Manager → aw-server & watchers: launches subprocesses and monitors stdout/exit codes
- aw-server ↔ watchers: watchers send activity events to the server’s REST endpoint
- Service Manager ← Configuration: reads config on startup, writes updates on user changes
- Autostart Script ↔ OS: installs or removes the aw-qt.desktop entry for login launch

##### Architectural patterns and design principles
- Modular separation: UI logic (trayicon.py) is decoupled from process-control logic (manager.py)
- Single responsibility: config, UI, and management each in its own module
- Externalization of assets and packaging: resources/ and scripts/ keep deployment concerns separate

## Diagram (Mermaid)

```mermaid
graph TB

  subgraph "aw-qt Application"
    EP1["__main__.py (Entry Point)"]:::python
    EP2["main.py (Entry Point)"]:::python
    UI["trayicon.py\n(System Tray UI)"]:::python
    MG["manager.py\n(Service Manager)"]:::python
    CF["config.py\n(Configuration)"]:::python
  end

  subgraph "External Services"
    AS["aw-server"]:::process
    WT["Watchers"]:::process
  end

  subgraph "OS/Desktop Integration"
    AScr["config-autostart.sh"]:::os
    Desk["aw-qt.desktop"]:::os
  end

  subgraph "Packaging & Build"
    MF["Makefile"]:::pack
    Spec["aw-qt.spec"]:::pack
    pyCfg["pyproject.toml"]:::pack
  end

  subgraph "Continuous Integration"
    CI1["build.yml"]:::ci
    CI2["codeql.yml"]:::ci
  end

  subgraph "Testing"
    E2E["integration_tests.py"]:::test
  end

  %% Application flows
  EP1 -->|"imports"| CF
  EP1 -->|"initializes"| MG
  EP1 -->|"starts GUI"| UI

  UI -->|"user actions"| MG
  UI -->|"config dialog"| CF

  MG -->|"reads/writes"| CF
  MG -->|"launch subprocess"| AS
  MG -->|"launch subprocess"| WT
  MG -->|"health checks"| AS
  MG -->|"monitors"| WT

  WT -->|"REST API calls"| AS
  AS -->|"responds to"| WT

  %% OS Integration
  AScr -->|"register/unregister"| Desk

  %% Packaging & Build flows
  pyCfg -->|"configures"| MF
  MF -->|"builds RPM"| Spec

  %% CI flows
  CI1 -->|"executes build"| MF
  CI2 -->|"scans codebase"| CF
  CI2 -->|"scans codebase"| MG
  CI2 -->|"scans codebase"| UI
  CI2 -->|"scans codebase"| EP1

  %% Testing
  CI1 -->|"runs tests"| E2E
  E2E -->|"tests CLI entry"| EP1

  %% Click Events
  click UI "https://github.com/activitywatch/aw-qt/blob/master/aw_qt/trayicon.py"
  click EP1 "https://github.com/activitywatch/aw-qt/blob/master/aw_qt/__main__.py"
  click EP2 "https://github.com/activitywatch/aw-qt/blob/master/aw_qt/main.py"
  click MG "https://github.com/activitywatch/aw-qt/blob/master/aw_qt/manager.py"
  click CF "https://github.com/activitywatch/aw-qt/blob/master/aw_qt/config.py"
  click AScr "https://github.com/activitywatch/aw-qt/blob/master/scripts/config-autostart.sh"
  click Desk "https://github.com/activitywatch/aw-qt/blob/master/resources/aw-qt.desktop"
  click MF "https://github.com/activitywatch/aw-qt/tree/master/Makefile"
  click Spec "https://github.com/activitywatch/aw-qt/blob/master/aw-qt.spec"
  click pyCfg "https://github.com/activitywatch/aw-qt/blob/master/pyproject.toml"
  click CI1 "https://github.com/activitywatch/aw-qt/blob/master/.github/workflows/build.yml"
  click CI2 "https://github.com/activitywatch/aw-qt/blob/master/.github/workflows/codeql.yml"
  click E2E "https://github.com/activitywatch/aw-qt/blob/master/tests/integration_tests.py"

  %% Styles
  classDef python fill:#AED6F1,stroke:#1B4F72,color:#1B2631
  classDef process fill:#ABEBC6,stroke:#145A32,color:#1D8348
  classDef os fill:#F9E79F,stroke:#B7950B,color:#7D6608
  classDef pack fill:#D2B4DE,stroke:#6C3483,color:#4A235A
  classDef ci fill:#F5B7B1,stroke:#922B21,color:#641E16
  classDef test fill:#FADBD8,stroke:#C0392B,color:#922B21
```
