# tarunjit45/agentwatch architecture

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

- Interactive diagram: https://gitdiagram.com/tarunjit45/agentwatch
- Repository: https://github.com/tarunjit45/agentwatch

## Overview

AgentWatch is an AI-agent observability platform. Agent code reports lifecycle events, logs, resource metrics, token usage, errors, and heartbeats through a non-blocking SDK; the server persists telemetry, evaluates costs and alert conditions, and streams events to dashboards and notification plugins. The dashboard combines REST summaries with live WebSocket events. The README documents broader API, cost, alert, and plugin capabilities than the sampled handlers show, so those branches use supported enclosing paths and omit uncertain handler-level wiring.

Main entry points: [`agentwatch/server/api`](https://github.com/tarunjit45/agentwatch/tree/main/agentwatch/server/api) (REST API), [`agentwatch/websocket/redis_pubsub.py`](https://github.com/tarunjit45/agentwatch/blob/main/agentwatch/websocket/redis_pubsub.py) (Pub/Sub manager), [`agentwatch/server/api/tasks.py`](https://github.com/tarunjit45/agentwatch/blob/main/agentwatch/server/api/tasks.py) (Task lifecycle), [`agentwatch/server/main.py`](https://github.com/tarunjit45/agentwatch/blob/main/agentwatch/server/main.py) (FastAPI server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Agent telemetry"]
  node_sdk["SDK client<br/>[client.py]"]
  node_collector["System collector<br/>[collector.py]"]
end

subgraph group_backend["Telemetry backend"]
  node_api["REST API"]
  node_server["FastAPI server<br/>[main.py]"]
  node_tasks["Task lifecycle<br/>[tasks.py]"]
  node_cost["Cost engine<br/>[cost.py]"]
  node_alerts["Alert engine<br/>[alerts.py]"]
end

subgraph group_state["Persistence and streaming"]
  node_dbsession["Database sessions<br/>[connection.py]"]
  node_models["Telemetry records<br/>[models.py]"]
  node_database[("SQLite / PostgreSQL")]
  node_pubsub["Pub/Sub manager<br/>[redis_pubsub.py]"]
  node_ws["WebSocket manager<br/>[manager.py]"]
end

subgraph group_views["Observability views"]
  node_dashboard["Textual dashboard<br/>[app.py]"]
  node_dashclient["Dashboard API client<br/>[api_client.py]"]
end

subgraph group_notifications["Alert delivery"]
  node_pluginmanager["Plugin manager<br/>[base.py]"]
  node_plugins["Notification plugins"]
end

node_agent(("AI agent code"))
node_redis[("Redis event bus")]
node_dashboarduser(("Dashboard user"))
node_providers{{"Notification services"}}

node_agent -->|"instruments"| node_sdk
node_sdk -->|"collects metrics"| node_collector
node_sdk -->|"posts telemetry"| node_api
node_server -->|"mounts routes"| node_api
node_api -->|"dispatches tasks"| node_tasks
node_tasks -->|"uses session"| node_dbsession
node_api -->|"persists telemetry"| node_dbsession
node_dbsession -->|"uses records"| node_models
node_dbsession -->|"reads and writes"| node_database
node_api -->|"calculates spend"| node_cost
node_api -->|"evaluates thresholds"| node_alerts
node_tasks -->|"checks duration"| node_alerts
node_tasks -->|"publishes events"| node_pubsub
node_server -->|"initializes and closes"| node_pubsub
node_pubsub -.->|"publishes events"| node_redis
node_pubsub -->|"broadcasts events"| node_ws
node_server -->|"accepts sockets"| node_ws
node_dashboarduser -->|"views telemetry"| node_dashboard
node_dashboard -->|"requests and listens"| node_dashclient
node_dashclient -->|"fetches summaries"| node_api
node_dashclient -->|"opens WebSocket"| node_server
node_pubsub -->|"dispatches events"| node_pluginmanager
node_pluginmanager -->|"broadcasts events"| node_plugins
node_plugins -.->|"sends notifications"| node_providers

click node_sdk "https://github.com/tarunjit45/agentwatch/blob/main/agentwatch/sdk/client.py"
click node_collector "https://github.com/tarunjit45/agentwatch/blob/main/agentwatch/sdk/collector.py"
click node_api "https://github.com/tarunjit45/agentwatch/tree/main/agentwatch/server/api"
click node_server "https://github.com/tarunjit45/agentwatch/blob/main/agentwatch/server/main.py"
click node_tasks "https://github.com/tarunjit45/agentwatch/blob/main/agentwatch/server/api/tasks.py"
click node_cost "https://github.com/tarunjit45/agentwatch/blob/main/agentwatch/telemetry/cost.py"
click node_alerts "https://github.com/tarunjit45/agentwatch/blob/main/agentwatch/telemetry/alerts.py"
click node_dbsession "https://github.com/tarunjit45/agentwatch/blob/main/agentwatch/database/connection.py"
click node_models "https://github.com/tarunjit45/agentwatch/blob/main/agentwatch/database/models.py"
click node_pubsub "https://github.com/tarunjit45/agentwatch/blob/main/agentwatch/websocket/redis_pubsub.py"
click node_ws "https://github.com/tarunjit45/agentwatch/blob/main/agentwatch/websocket/manager.py"
click node_dashboard "https://github.com/tarunjit45/agentwatch/blob/main/agentwatch/dashboard/app.py"
click node_dashclient "https://github.com/tarunjit45/agentwatch/blob/main/agentwatch/dashboard/api_client.py"
click node_pluginmanager "https://github.com/tarunjit45/agentwatch/blob/main/agentwatch/plugins/base.py"
click node_plugins "https://github.com/tarunjit45/agentwatch/tree/main/agentwatch/plugins"

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_sdk,node_collector,node_dashboarduser toneBlue
class node_api,node_server,node_tasks,node_cost,node_alerts,node_redis toneAmber
class node_dbsession,node_models,node_database,node_pubsub,node_ws toneMint
class node_dashboard,node_dashclient toneRose
class node_pluginmanager,node_plugins,node_agent,node_providers toneIndigo
```

## Components

### Agent telemetry

- [SDK client](https://github.com/tarunjit45/agentwatch/blob/main/agentwatch/sdk/client.py): `agentwatch/sdk/client.py`
- [System collector](https://github.com/tarunjit45/agentwatch/blob/main/agentwatch/sdk/collector.py): `agentwatch/sdk/collector.py`

### Telemetry backend

- [REST API](https://github.com/tarunjit45/agentwatch/tree/main/agentwatch/server/api): `agentwatch/server/api`
- [FastAPI server](https://github.com/tarunjit45/agentwatch/blob/main/agentwatch/server/main.py): `agentwatch/server/main.py`
- [Task lifecycle](https://github.com/tarunjit45/agentwatch/blob/main/agentwatch/server/api/tasks.py): `agentwatch/server/api/tasks.py`
- [Cost engine](https://github.com/tarunjit45/agentwatch/blob/main/agentwatch/telemetry/cost.py): `agentwatch/telemetry/cost.py`
- [Alert engine](https://github.com/tarunjit45/agentwatch/blob/main/agentwatch/telemetry/alerts.py): `agentwatch/telemetry/alerts.py`

### Persistence and streaming

- [Database sessions](https://github.com/tarunjit45/agentwatch/blob/main/agentwatch/database/connection.py): `agentwatch/database/connection.py`
- [Telemetry records](https://github.com/tarunjit45/agentwatch/blob/main/agentwatch/database/models.py): `agentwatch/database/models.py`
- **SQLite / PostgreSQL**
- [Pub/Sub manager](https://github.com/tarunjit45/agentwatch/blob/main/agentwatch/websocket/redis_pubsub.py): `agentwatch/websocket/redis_pubsub.py`
- [WebSocket manager](https://github.com/tarunjit45/agentwatch/blob/main/agentwatch/websocket/manager.py): `agentwatch/websocket/manager.py`

### Observability views

- [Textual dashboard](https://github.com/tarunjit45/agentwatch/blob/main/agentwatch/dashboard/app.py): `agentwatch/dashboard/app.py`
- [Dashboard API client](https://github.com/tarunjit45/agentwatch/blob/main/agentwatch/dashboard/api_client.py): `agentwatch/dashboard/api_client.py`

### Alert delivery

- [Plugin manager](https://github.com/tarunjit45/agentwatch/blob/main/agentwatch/plugins/base.py): `agentwatch/plugins/base.py`
- [Notification plugins](https://github.com/tarunjit45/agentwatch/tree/main/agentwatch/plugins): `agentwatch/plugins`

### Other components

- **AI agent code**
- **Redis event bus**
- **Dashboard user**
- **Notification services**

## Connections

- AI agent code → SDK client: instruments
- SDK client → System collector: collects metrics
- SDK client → REST API: posts telemetry
- FastAPI server → REST API: mounts routes
- REST API → Task lifecycle: dispatches tasks
- Task lifecycle → Database sessions: uses session
- REST API → Database sessions: persists telemetry
- Database sessions → Telemetry records: uses records
- Database sessions → SQLite / PostgreSQL: reads and writes
- REST API → Cost engine: calculates spend
- REST API → Alert engine: evaluates thresholds
- Task lifecycle → Alert engine: checks duration
- Task lifecycle → Pub/Sub manager: publishes events
- FastAPI server → Pub/Sub manager: initializes and closes
- Pub/Sub manager → Redis event bus: publishes events
- Pub/Sub manager → WebSocket manager: broadcasts events
- FastAPI server → WebSocket manager: accepts sockets
- Dashboard user → Textual dashboard: views telemetry
- Textual dashboard → Dashboard API client: requests and listens
- Dashboard API client → REST API: fetches summaries
- Dashboard API client → FastAPI server: opens WebSocket
- Pub/Sub manager → Plugin manager: dispatches events
- Plugin manager → Notification plugins: broadcasts events
- Notification plugins → Notification services: sends notifications