# 2coderok/ai-buddy architecture

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

- Interactive diagram: https://gitdiagram.com/2coderok/ai-buddy
- Repository: https://github.com/2coderok/ai-buddy

## Overview

AI Buddy is a local desktop productivity coach. The main workflow is: the app starts a tracker and coaching loop; the tracker samples foreground-window activity into SQLite; the coach periodically reads summaries, prompts a local GGUF model, and sends a notification. The tray also exposes pause/resume controls, and the tracker supports standalone screen-time statistics. The graph covers the documented daily-goal coaching capability, though its prompt file is not in the provided tree. Relationships are limited to calls shown in excerpts or documented in the README/source index.

Main entry points: [`src/buddy.py`](https://github.com/2coderok/ai-buddy/blob/main/src/buddy.py) (Analysis Loop), [`src/main.py`](https://github.com/2coderok/ai-buddy/blob/main/src/main.py) (App & Tray), [`src/tracker.py`](https://github.com/2coderok/ai-buddy/blob/main/src/tracker.py) (Window Tracker & Stats), [`src/config.py`](https://github.com/2coderok/ai-buddy/blob/main/src/config.py) (App Configuration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App Control"]
  node_entry["App &amp; Tray<br/>[main.py]"]
  node_pause["Pause State<br/>[pause_state.py]"]
end

subgraph group_activity["Activity Tracking"]
  node_tracker["Window Tracker &amp; Stats<br/>[tracker.py]"]
  node_database[("Activity Database<br/>[db.py]")]
end

subgraph group_coaching["Coaching"]
  node_coach["Analysis Loop<br/>[buddy.py]"]
  node_prompt["Coaching Instructions<br/>[buddy.py]"]
  node_model["Local GGUF Model"]
  node_notify["Notification Dispatcher<br/>[notifier.py]"]
end

subgraph group_support["Shared Services"]
  node_config["App Configuration<br/>[config.py]"]
end

node_user(("User"))
node_platform["Platform Notifications"]

node_user -->|"starts app"| node_entry
node_entry -->|"starts thread"| node_tracker
node_entry -->|"starts thread"| node_coach
node_entry -->|"controls pause"| node_pause
node_tracker -->|"writes activity"| node_database
node_tracker -->|"reads statistics"| node_database
node_coach -->|"reads summaries"| node_database
node_coach -->|"checks pause"| node_pause
node_coach -->|"loads instructions"| node_prompt
node_coach -->|"runs inference"| node_model
node_coach -->|"sends coaching"| node_notify
node_notify -->|"dispatches alert"| node_platform
node_tracker -->|"reads settings"| node_config
node_coach -->|"reads settings"| node_config
node_notify -->|"reads settings"| node_config
node_entry -->|"reads settings"| node_config

click node_entry "https://github.com/2coderok/ai-buddy/blob/main/src/main.py"
click node_tracker "https://github.com/2coderok/ai-buddy/blob/main/src/tracker.py"
click node_database "https://github.com/2coderok/ai-buddy/blob/main/src/db.py"
click node_coach "https://github.com/2coderok/ai-buddy/blob/main/src/buddy.py"
click node_prompt "https://github.com/2coderok/ai-buddy/blob/main/src/buddy.py"
click node_pause "https://github.com/2coderok/ai-buddy/blob/main/src/pause_state.py"
click node_notify "https://github.com/2coderok/ai-buddy/blob/main/src/notifier.py"
click node_config "https://github.com/2coderok/ai-buddy/blob/main/src/config.py"

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_entry,node_pause,node_user toneBlue
class node_tracker,node_database toneAmber
class node_coach,node_prompt,node_model,node_notify toneMint
class node_config toneRose
class node_platform toneIndigo
```

## Components

### App Control

- [App & Tray](https://github.com/2coderok/ai-buddy/blob/main/src/main.py): `src/main.py`
- [Pause State](https://github.com/2coderok/ai-buddy/blob/main/src/pause_state.py): `src/pause_state.py`

### Activity Tracking

- [Window Tracker & Stats](https://github.com/2coderok/ai-buddy/blob/main/src/tracker.py): `src/tracker.py`
- [Activity Database](https://github.com/2coderok/ai-buddy/blob/main/src/db.py): `src/db.py`

### Coaching

- [Analysis Loop](https://github.com/2coderok/ai-buddy/blob/main/src/buddy.py): `src/buddy.py`
- [Coaching Instructions](https://github.com/2coderok/ai-buddy/blob/main/src/buddy.py): `src/buddy.py`
- **Local GGUF Model**
- [Notification Dispatcher](https://github.com/2coderok/ai-buddy/blob/main/src/notifier.py): `src/notifier.py`

### Shared Services

- [App Configuration](https://github.com/2coderok/ai-buddy/blob/main/src/config.py): `src/config.py`

### Other components

- **User**
- **Platform Notifications**

## Connections

- User → App & Tray: starts app (evidence: `README.md`)
- App & Tray → Window Tracker & Stats: starts thread (evidence: `src/main.py`)
- App & Tray → Analysis Loop: starts thread (evidence: `src/main.py`)
- App & Tray → Pause State: controls pause (evidence: `src/main.py`)
- Window Tracker & Stats → Activity Database: writes activity (evidence: `src/tracker.py`)
- Window Tracker & Stats → Activity Database: reads statistics (evidence: `src/tracker.py`)
- Analysis Loop → Activity Database: reads summaries (evidence: `src/buddy.py`)
- Analysis Loop → Pause State: checks pause (evidence: `src/buddy.py`)
- Analysis Loop → Coaching Instructions: loads instructions (evidence: `src/buddy.py`)
- Analysis Loop → Local GGUF Model: runs inference (evidence: `src/buddy.py`)
- Analysis Loop → Notification Dispatcher: sends coaching (evidence: `src/buddy.py`)
- Notification Dispatcher → Platform Notifications: dispatches alert (evidence: `src/notifier.py`)
- Window Tracker & Stats → App Configuration: reads settings (evidence: `src/tracker.py`)
- Analysis Loop → App Configuration: reads settings (evidence: `src/buddy.py`)
- Notification Dispatcher → App Configuration: reads settings (evidence: `src/notifier.py`)
- App & Tray → App Configuration: reads settings (evidence: `src/main.py`)