# romboooo/ttracker architecture

> Architecture diagram of the GitHub repository romboooo/ttracker, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/romboooo/ttracker
- Repository: https://github.com/romboooo/ttracker

## Overview

ttracker records focused-window sessions from Hyprland, persists them in SQLite, and reports per-application durations through its CLI and Noctalia panel. The graph includes the documented live-status and icon capabilities. Source excerpts show the Go runtime calls; plugin internals were not sampled, so plugin wiring is represented only where documented or marked unverified.

Main entry points: [`cli`](https://github.com/romboooo/ttracker/tree/main/cli) (CLI commands), [`tracker/run.go`](https://github.com/romboooo/ttracker/blob/main/tracker/run.go) (Event tracker), [`storage/db.go`](https://github.com/romboooo/ttracker/blob/main/storage/db.go) (SQLite storage), [`tracker/active.go`](https://github.com/romboooo/ttracker/blob/main/tracker/active.go) (Live status file)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI and service"]
  node_cli["CLI commands"]
  node_service["User service<br/>[ttracker.service]"]
end

subgraph group_tracking["Focus tracking"]
  node_tracker["Event tracker<br/>[run.go]"]
  node_active["Live status file<br/>[active.go]"]
end

subgraph group_insights["Statistics and display"]
  node_report["Period reports<br/>[report.go]"]
  node_icons["Desktop icon lookup<br/>[icons.go]"]
  node_plugin["Noctalia panel"]
end

subgraph group_persistence["Session data"]
  node_storage[("SQLite storage<br/>[db.go]")]
  node_session["Session model<br/>[session.go]"]
end

node_user(("User"))
node_hyprland["Hyprland"]

node_user -->|"runs commands"| node_cli
node_service -->|"runs tracker"| node_cli
node_cli -->|"starts tracking"| node_tracker
node_cli -->|"opens database"| node_storage
node_cli -->|"requests periods"| node_report
node_cli -->|"reads live status"| node_active
node_cli -->|"looks up icons"| node_icons
node_tracker -->|"reads focus events"| node_hyprland
node_tracker -->|"saves sessions"| node_storage
node_tracker -->|"writes live status"| node_active
node_storage -->|"maps sessions"| node_session
node_report -->|"summarizes sessions"| node_session
node_plugin -->|"reads live status"| node_active
node_plugin -.->|"loads statistics"| node_cli

click node_cli "https://github.com/romboooo/ttracker/tree/main/cli"
click node_service "https://github.com/romboooo/ttracker/blob/main/systemd/ttracker.service"
click node_tracker "https://github.com/romboooo/ttracker/blob/main/tracker/run.go"
click node_active "https://github.com/romboooo/ttracker/blob/main/tracker/active.go"
click node_storage "https://github.com/romboooo/ttracker/blob/main/storage/db.go"
click node_session "https://github.com/romboooo/ttracker/blob/main/model/session.go"
click node_report "https://github.com/romboooo/ttracker/blob/main/report/report.go"
click node_icons "https://github.com/romboooo/ttracker/blob/main/desktop/icons.go"
click node_plugin "https://github.com/romboooo/ttracker/tree/main/noctalia-plugin/ttracker"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_service,node_user toneBlue
class node_tracker,node_active toneAmber
class node_report,node_icons,node_plugin toneMint
class node_storage,node_session toneRose
class node_hyprland toneIndigo
```

## Components

### CLI and service

- [CLI commands](https://github.com/romboooo/ttracker/tree/main/cli): `cli`
- [User service](https://github.com/romboooo/ttracker/blob/main/systemd/ttracker.service): `systemd/ttracker.service`

### Focus tracking

- [Event tracker](https://github.com/romboooo/ttracker/blob/main/tracker/run.go): `tracker/run.go`
- [Live status file](https://github.com/romboooo/ttracker/blob/main/tracker/active.go): `tracker/active.go`

### Statistics and display

- [Period reports](https://github.com/romboooo/ttracker/blob/main/report/report.go): `report/report.go`
- [Desktop icon lookup](https://github.com/romboooo/ttracker/blob/main/desktop/icons.go): `desktop/icons.go`
- [Noctalia panel](https://github.com/romboooo/ttracker/tree/main/noctalia-plugin/ttracker): `noctalia-plugin/ttracker`

### Session data

- [SQLite storage](https://github.com/romboooo/ttracker/blob/main/storage/db.go): `storage/db.go`
- [Session model](https://github.com/romboooo/ttracker/blob/main/model/session.go): `model/session.go`

### Other components

- **User**
- **Hyprland**

## Connections

- User → CLI commands: runs commands (evidence: `README.md`)
- User service → CLI commands: runs tracker (evidence: `README.md`)
- CLI commands → Event tracker: starts tracking (evidence: `cli/run.go`)
- CLI commands → SQLite storage: opens database (evidence: `cli/stats.go`)
- CLI commands → Period reports: requests periods (evidence: `cli/stats.go`)
- CLI commands → Live status file: reads live status (evidence: `cli/stats.go`)
- CLI commands → Desktop icon lookup: looks up icons (evidence: `cli/stats.go`)
- Event tracker → Hyprland: reads focus events (evidence: `tracker/run.go`)
- Event tracker → SQLite storage: saves sessions (evidence: `tracker/run.go`)
- Event tracker → Live status file: writes live status (evidence: `tracker/run.go`)
- SQLite storage → Session model: maps sessions (evidence: `storage/db.go`)
- Period reports → Session model: summarizes sessions (evidence: `report/report.go`)
- Noctalia panel → Live status file: reads live status (evidence: `README.md`)
- Noctalia panel → CLI commands: loads statistics