# watanabe3tipapa/var-watcher architecture

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

- Interactive diagram: https://gitdiagram.com/watanabe3tipapa/var-watcher
- Repository: https://github.com/watanabe3tipapa/var-watcher

## Overview

var-watcher monitors macOS /var activity through several watcher engines and presents a shared event stream in a terminal UI and a Web UI. Its main workflow loads configuration, starts watchers, and distributes events to live views and optional analysis or persistence services. The Web UI also exposes search, export, alerts, statistics, trees, diffs, presets, and performance data. Edges reflect the sampled entry point and server/UI excerpts or README statements; several subsystem internals were not sampled, so their precise wiring is not expanded.

Main entry points: [`cmd/varwatch/main.go`](https://github.com/watanabe3tipapa/var-watcher/blob/main/cmd/varwatch/main.go) (Process Entry), [`internal/web/server.go`](https://github.com/watanabe3tipapa/var-watcher/blob/main/internal/web/server.go) (Web API Server), [`internal/engine/engine.go`](https://github.com/watanabe3tipapa/var-watcher/blob/main/internal/engine/engine.go) (Watcher Engine), [`internal/engine/bus.go`](https://github.com/watanabe3tipapa/var-watcher/blob/main/internal/engine/bus.go) (Event Bus)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime and Watchers"]
  node_main["Process Entry<br/>[main.go]"]
  node_engine["Watcher Engine<br/>[engine.go]"]
  node_watchers["Watch Sources<br/>[watcher.go]"]
  node_bus["Event Bus<br/>[bus.go]"]
end

subgraph group_analysis["Event Analysis"]
  node_alerts["Alert Rules<br/>[alert.go]"]
  node_diffs["File Diffs<br/>[diff.go]"]
  node_performance["Performance Monitor<br/>[perf.go]"]
end

subgraph group_storage["Persistence and Search"]
  node_store[("SQLite Log Store<br/>[store.go]")]
  node_statistics["Statistics<br/>[stats.go]"]
  node_directory_tree["Directory Tree<br/>[tree.go]"]
end

subgraph group_interfaces["User Interfaces"]
  node_tui["Terminal UI<br/>[tui.go]"]
  node_web["Web API Server<br/>[server.go]"]
  node_frontend["Web Dashboard<br/>[App.vue]"]
  node_i18n["Language Catalogs<br/>[en.ts]"]
  node_japanese["Japanese Catalog<br/>[ja.ts]"]
end

subgraph group_support["Configuration and Integrations"]
  node_config["Configuration<br/>[config.go]"]
  node_plugins["Shell Plugins<br/>[plugin.go]"]
  node_notify["macOS Notifications<br/>[notify.go]"]
end

node_operator(("Operator"))
node_macos["macOS /var"]
node_watch_commands["Watcher Commands"]

node_operator -->|"starts"| node_main
node_main -->|"loads"| node_config
node_main -->|"initializes"| node_engine
node_main -->|"opens"| node_store
node_main -->|"discovers"| node_plugins
node_main -->|"starts"| node_alerts
node_main -->|"starts capture"| node_diffs
node_main -->|"starts"| node_performance
node_main -->|"starts"| node_web
node_main -->|"starts"| node_tui
node_engine -->|"builds"| node_watchers
node_watchers -->|"monitors"| node_macos
node_watchers -->|"runs"| node_watch_commands
node_plugins -->|"registers"| node_engine
node_engine -.->|"publishes events"| node_bus
node_alerts -->|"subscribes"| node_bus
node_main -->|"persists events"| node_bus
node_bus -->|"appends logs"| node_store
node_main -->|"captures diffs"| node_bus
node_main -->|"counts events"| node_bus
node_main -->|"sends alerts"| node_notify
node_tui -->|"controls watchers"| node_engine
node_tui -->|"exports logs"| node_store
node_web -->|"controls watchers"| node_engine
node_web -->|"queries logs"| node_store
node_web -->|"requests aggregates"| node_statistics
node_web -->|"requests hierarchy"| node_directory_tree
node_web -->|"reads history"| node_diffs
node_web -->|"reads history"| node_alerts
node_web -->|"serves samples"| node_performance
node_frontend -->|"requests API"| node_web
node_frontend -->|"uses translations"| node_i18n
node_i18n -->|"loads catalog"| node_japanese
node_frontend -->|"shows dashboard"| node_operator

click node_main "https://github.com/watanabe3tipapa/var-watcher/blob/main/cmd/varwatch/main.go"
click node_config "https://github.com/watanabe3tipapa/var-watcher/blob/main/internal/config/config.go"
click node_engine "https://github.com/watanabe3tipapa/var-watcher/blob/main/internal/engine/engine.go"
click node_watchers "https://github.com/watanabe3tipapa/var-watcher/blob/main/internal/engine/watcher.go"
click node_bus "https://github.com/watanabe3tipapa/var-watcher/blob/main/internal/engine/bus.go"
click node_plugins "https://github.com/watanabe3tipapa/var-watcher/blob/main/internal/plugin/plugin.go"
click node_alerts "https://github.com/watanabe3tipapa/var-watcher/blob/main/internal/alert/alert.go"
click node_diffs "https://github.com/watanabe3tipapa/var-watcher/blob/main/internal/diff/diff.go"
click node_performance "https://github.com/watanabe3tipapa/var-watcher/blob/main/internal/perf/perf.go"
click node_store "https://github.com/watanabe3tipapa/var-watcher/blob/main/internal/store/store.go"
click node_statistics "https://github.com/watanabe3tipapa/var-watcher/blob/main/internal/store/stats.go"
click node_directory_tree "https://github.com/watanabe3tipapa/var-watcher/blob/main/internal/store/tree.go"
click node_tui "https://github.com/watanabe3tipapa/var-watcher/blob/main/internal/tui/tui.go"
click node_web "https://github.com/watanabe3tipapa/var-watcher/blob/main/internal/web/server.go"
click node_frontend "https://github.com/watanabe3tipapa/var-watcher/blob/main/frontend/src/App.vue"
click node_i18n "https://github.com/watanabe3tipapa/var-watcher/blob/main/frontend/src/i18n/en.ts"
click node_japanese "https://github.com/watanabe3tipapa/var-watcher/blob/main/frontend/src/i18n/ja.ts"
click node_notify "https://github.com/watanabe3tipapa/var-watcher/blob/main/internal/notify/notify.go"

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_main,node_engine,node_watchers,node_bus toneBlue
class node_alerts,node_diffs,node_performance toneAmber
class node_store,node_statistics,node_directory_tree toneMint
class node_tui,node_web,node_frontend,node_i18n,node_japanese toneRose
class node_config,node_plugins,node_notify,node_operator,node_macos,node_watch_commands toneIndigo
```

## Components

### Runtime and Watchers

- [Process Entry](https://github.com/watanabe3tipapa/var-watcher/blob/main/cmd/varwatch/main.go): `cmd/varwatch/main.go`
- [Watcher Engine](https://github.com/watanabe3tipapa/var-watcher/blob/main/internal/engine/engine.go): `internal/engine/engine.go`
- [Watch Sources](https://github.com/watanabe3tipapa/var-watcher/blob/main/internal/engine/watcher.go): `internal/engine/watcher.go`
- [Event Bus](https://github.com/watanabe3tipapa/var-watcher/blob/main/internal/engine/bus.go): `internal/engine/bus.go`

### Event Analysis

- [Alert Rules](https://github.com/watanabe3tipapa/var-watcher/blob/main/internal/alert/alert.go): `internal/alert/alert.go`
- [File Diffs](https://github.com/watanabe3tipapa/var-watcher/blob/main/internal/diff/diff.go): `internal/diff/diff.go`
- [Performance Monitor](https://github.com/watanabe3tipapa/var-watcher/blob/main/internal/perf/perf.go): `internal/perf/perf.go`

### Persistence and Search

- [SQLite Log Store](https://github.com/watanabe3tipapa/var-watcher/blob/main/internal/store/store.go): `internal/store/store.go`
- [Statistics](https://github.com/watanabe3tipapa/var-watcher/blob/main/internal/store/stats.go): `internal/store/stats.go`
- [Directory Tree](https://github.com/watanabe3tipapa/var-watcher/blob/main/internal/store/tree.go): `internal/store/tree.go`

### User Interfaces

- [Terminal UI](https://github.com/watanabe3tipapa/var-watcher/blob/main/internal/tui/tui.go): `internal/tui/tui.go`
- [Web API Server](https://github.com/watanabe3tipapa/var-watcher/blob/main/internal/web/server.go): `internal/web/server.go`
- [Web Dashboard](https://github.com/watanabe3tipapa/var-watcher/blob/main/frontend/src/App.vue): `frontend/src/App.vue`
- [Language Catalogs](https://github.com/watanabe3tipapa/var-watcher/blob/main/frontend/src/i18n/en.ts): `frontend/src/i18n/en.ts`
- [Japanese Catalog](https://github.com/watanabe3tipapa/var-watcher/blob/main/frontend/src/i18n/ja.ts): `frontend/src/i18n/ja.ts`

### Configuration and Integrations

- [Configuration](https://github.com/watanabe3tipapa/var-watcher/blob/main/internal/config/config.go): `internal/config/config.go`
- [Shell Plugins](https://github.com/watanabe3tipapa/var-watcher/blob/main/internal/plugin/plugin.go): `internal/plugin/plugin.go`
- [macOS Notifications](https://github.com/watanabe3tipapa/var-watcher/blob/main/internal/notify/notify.go): `internal/notify/notify.go`

### Other components

- **Operator**
- **macOS /var**
- **Watcher Commands**

## Connections

- Operator → Process Entry: starts (evidence: `README.md`)
- Process Entry → Configuration: loads (evidence: `cmd/varwatch/main.go`)
- Process Entry → Watcher Engine: initializes (evidence: `cmd/varwatch/main.go`)
- Process Entry → SQLite Log Store: opens (evidence: `cmd/varwatch/main.go`)
- Process Entry → Shell Plugins: discovers (evidence: `cmd/varwatch/main.go`)
- Process Entry → Alert Rules: starts (evidence: `cmd/varwatch/main.go`)
- Process Entry → File Diffs: starts capture (evidence: `cmd/varwatch/main.go`)
- Process Entry → Performance Monitor: starts (evidence: `cmd/varwatch/main.go`)
- Process Entry → Web API Server: starts (evidence: `cmd/varwatch/main.go`)
- Process Entry → Terminal UI: starts (evidence: `cmd/varwatch/main.go`)
- Watcher Engine → Watch Sources: builds (evidence: `internal/engine/engine.go`)
- Watch Sources → macOS /var: monitors (evidence: `README.md`)
- Watch Sources → Watcher Commands: runs (evidence: `README.md`)
- Shell Plugins → Watcher Engine: registers
- Watcher Engine → Event Bus: publishes events
- Alert Rules → Event Bus: subscribes (evidence: `internal/alert/alert.go`)
- Process Entry → Event Bus: persists events (evidence: `cmd/varwatch/main.go`)
- Event Bus → SQLite Log Store: appends logs
- Process Entry → Event Bus: captures diffs (evidence: `cmd/varwatch/main.go`)
- Process Entry → Event Bus: counts events (evidence: `cmd/varwatch/main.go`)
- Process Entry → macOS Notifications: sends alerts (evidence: `cmd/varwatch/main.go`)
- Terminal UI → Watcher Engine: controls watchers (evidence: `internal/tui/tui.go`)
- Terminal UI → SQLite Log Store: exports logs (evidence: `internal/tui/tui.go`)
- Web API Server → Watcher Engine: controls watchers (evidence: `internal/web/server.go`)
- Web API Server → SQLite Log Store: queries logs (evidence: `internal/web/server.go`)
- Web API Server → Statistics: requests aggregates (evidence: `internal/web/server.go`)
- Web API Server → Directory Tree: requests hierarchy (evidence: `internal/web/server.go`)
- Web API Server → File Diffs: reads history (evidence: `internal/web/server.go`)
- Web API Server → Alert Rules: reads history (evidence: `README.md`)
- Web API Server → Performance Monitor: serves samples (evidence: `README.md`)
- Web Dashboard → Web API Server: requests API (evidence: `frontend/src/App.vue`)
- Web Dashboard → Language Catalogs: uses translations (evidence: `frontend/src/App.vue`)
- Language Catalogs → Japanese Catalog: loads catalog (evidence: `frontend/src/i18n/index.ts`)
- Web Dashboard → Operator: shows dashboard (evidence: `README.md`)
