# mikky00b/watchdog architecture

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

- Interactive diagram: https://gitdiagram.com/mikky00b/watchdog
- Repository: https://github.com/mikky00b/watchdog

## Overview

WATCHDOG is a team-oriented uptime and heartbeat monitoring platform. Users register and verify an account, create an organization and optional clients, configure monitors and alert channels, then view incidents, status pages, and monthly reliability reports. The monitoring runtime checks endpoints and heartbeats, evaluates results, and produces incident alerts that are queued for channel delivery. The graph includes the documented product branches; unsampled implementations are represented by their existing module paths, and their relationships are shown only where the README or indexed source references support them.

Main entry points: [`src/monitoring/database.py`](https://github.com/mikky00b/watchdog/blob/main/src/monitoring/database.py) (PostgreSQL data), [`src/monitoring/main.py`](https://github.com/mikky00b/watchdog/blob/main/src/monitoring/main.py) (FastAPI application), [`src/monitoring/workers/scheduler.py`](https://github.com/mikky00b/watchdog/blob/main/src/monitoring/workers/scheduler.py) (Monitor scheduler), [`src/monitoring/services/auth_service.py`](https://github.com/mikky00b/watchdog/blob/main/src/monitoring/services/auth_service.py) (Identity service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_frontend["Web dashboard<br/>[App.tsx]"]
  node_frontend_api["API client<br/>[services.ts]"]
end

subgraph group_api["API and identity"]
  node_api_app["FastAPI application<br/>[main.py]"]
  node_auth_api["Authentication API<br/>[auth.py]"]
  node_auth["Identity service<br/>[auth_service.py]"]
  node_org_api["Organization and client APIs<br/>[organizations.py]"]
  node_monitor_api["Monitor and check APIs<br/>[monitors.py]"]
  node_alert_api["Alert channel API<br/>[alert_channels.py]"]
  node_report_api["Reports API<br/>[reports.py]"]
  node_status_api["Status page API<br/>[status_pages.py]"]
end

subgraph group_monitoring["Monitoring runtime"]
  node_scheduler["Monitor scheduler<br/>[scheduler.py]"]
  node_checker["Check execution<br/>[checker_service.py]"]
  node_rules["Rule evaluation<br/>[rule_engine.py]"]
  node_monitor_service["Monitor management<br/>[monitor_service.py]"]
end

subgraph group_alerts["Incident and alerting"]
  node_incident_service["Incident handling"]
  node_alert_service["Alert management<br/>[alert_service.py]"]
  node_notification_service["Notification delivery"]
  node_notification_worker["Notification worker"]
  node_channel_senders["Email and Telegram senders"]
  node_telegram_api["Telegram integration<br/>[telegram.py]"]
end

subgraph group_data["Domain data"]
  node_report_service["Reliability reports<br/>[report_service.py]"]
  node_status_service["Status page service"]
  node_database[("PostgreSQL data<br/>[database.py]")]
  node_models["Domain records"]
end

node_user(("Team user"))

node_user -->|"uses"| node_frontend
node_frontend -->|"requests through"| node_frontend_api
node_frontend_api -->|"calls API"| node_api_app
node_api_app -->|"routes to"| node_auth_api
node_api_app -->|"routes to"| node_org_api
node_api_app -->|"routes to"| node_monitor_api
node_api_app -->|"routes to"| node_alert_api
node_api_app -->|"routes to"| node_report_api
node_api_app -->|"routes to"| node_status_api
node_auth_api -->|"delegates to"| node_auth
node_auth -->|"reads and writes"| node_database
node_auth -->|"sends auth email"| node_channel_senders
node_monitor_api -->|"delegates to"| node_monitor_service
node_monitor_service -->|"runs manual checks"| node_checker
node_scheduler -->|"runs scheduled checks"| node_checker
node_scheduler -->|"evaluates results"| node_rules
node_scheduler -->|"handles incidents"| node_incident_service
node_scheduler -->|"creates alerts"| node_alert_service
node_checker -->|"stores check results"| node_database
node_rules -->|"reads check history"| node_database
node_incident_service -.->|"stores incidents"| node_database
node_alert_service -->|"stores alerts"| node_database
node_alert_service -.->|"queues notifications"| node_notification_service
node_notification_worker -->|"sends pending events"| node_notification_service
node_notification_service -->|"dispatches channels"| node_channel_senders
node_channel_senders -.->|"delivers alerts"| node_user
node_telegram_api -.->|"uses session"| node_database
node_report_api -.->|"generates reports"| node_report_service
node_report_service -->|"reads monitoring history"| node_database
node_status_api -.->|"serves status pages"| node_status_service
node_status_service -.->|"reads status data"| node_database
node_database -->|"persists records"| node_models

click node_frontend "https://github.com/mikky00b/watchdog/blob/main/frontend/src/ui/App.tsx"
click node_frontend_api "https://github.com/mikky00b/watchdog/blob/main/frontend/src/services.ts"
click node_api_app "https://github.com/mikky00b/watchdog/blob/main/src/monitoring/main.py"
click node_auth_api "https://github.com/mikky00b/watchdog/blob/main/src/monitoring/api/v1/auth.py"
click node_auth "https://github.com/mikky00b/watchdog/blob/main/src/monitoring/services/auth_service.py"
click node_org_api "https://github.com/mikky00b/watchdog/blob/main/src/monitoring/api/v1/organizations.py"
click node_monitor_api "https://github.com/mikky00b/watchdog/blob/main/src/monitoring/api/v1/monitors.py"
click node_alert_api "https://github.com/mikky00b/watchdog/blob/main/src/monitoring/api/v1/alert_channels.py"
click node_report_api "https://github.com/mikky00b/watchdog/blob/main/src/monitoring/api/v1/reports.py"
click node_status_api "https://github.com/mikky00b/watchdog/blob/main/src/monitoring/api/v1/status_pages.py"
click node_scheduler "https://github.com/mikky00b/watchdog/blob/main/src/monitoring/workers/scheduler.py"
click node_checker "https://github.com/mikky00b/watchdog/blob/main/src/monitoring/services/checker_service.py"
click node_rules "https://github.com/mikky00b/watchdog/blob/main/src/monitoring/services/rule_engine.py"
click node_monitor_service "https://github.com/mikky00b/watchdog/blob/main/src/monitoring/services/monitor_service.py"
click node_incident_service "https://github.com/mikky00b/watchdog/blob/main/src/monitoring/services/incident_service.py"
click node_alert_service "https://github.com/mikky00b/watchdog/blob/main/src/monitoring/services/alert_service.py"
click node_notification_service "https://github.com/mikky00b/watchdog/blob/main/src/monitoring/services/notification_service.py"
click node_notification_worker "https://github.com/mikky00b/watchdog/blob/main/src/monitoring/workers/notification_worker.py"
click node_channel_senders "https://github.com/mikky00b/watchdog/tree/main/src/monitoring/alerting"
click node_telegram_api "https://github.com/mikky00b/watchdog/blob/main/src/monitoring/api/v1/integrations/telegram.py"
click node_report_service "https://github.com/mikky00b/watchdog/blob/main/src/monitoring/services/report_service.py"
click node_status_service "https://github.com/mikky00b/watchdog/blob/main/src/monitoring/services/status_page_service.py"
click node_database "https://github.com/mikky00b/watchdog/blob/main/src/monitoring/database.py"
click node_models "https://github.com/mikky00b/watchdog/tree/main/src/monitoring/models"

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_frontend,node_frontend_api,node_user toneBlue
class node_api_app,node_auth_api,node_auth,node_org_api,node_monitor_api,node_alert_api,node_report_api,node_status_api toneAmber
class node_scheduler,node_checker,node_rules,node_monitor_service toneMint
class node_incident_service,node_alert_service,node_notification_service,node_notification_worker,node_channel_senders,node_telegram_api toneRose
class node_report_service,node_status_service,node_database,node_models toneIndigo
```

## Components

### User experience

- [Web dashboard](https://github.com/mikky00b/watchdog/blob/main/frontend/src/ui/App.tsx): `frontend/src/ui/App.tsx`
- [API client](https://github.com/mikky00b/watchdog/blob/main/frontend/src/services.ts): `frontend/src/services.ts`

### API and identity

- [FastAPI application](https://github.com/mikky00b/watchdog/blob/main/src/monitoring/main.py): `src/monitoring/main.py`
- [Authentication API](https://github.com/mikky00b/watchdog/blob/main/src/monitoring/api/v1/auth.py): `src/monitoring/api/v1/auth.py`
- [Identity service](https://github.com/mikky00b/watchdog/blob/main/src/monitoring/services/auth_service.py): `src/monitoring/services/auth_service.py`
- [Organization and client APIs](https://github.com/mikky00b/watchdog/blob/main/src/monitoring/api/v1/organizations.py): `src/monitoring/api/v1/organizations.py`
- [Monitor and check APIs](https://github.com/mikky00b/watchdog/blob/main/src/monitoring/api/v1/monitors.py): `src/monitoring/api/v1/monitors.py`
- [Alert channel API](https://github.com/mikky00b/watchdog/blob/main/src/monitoring/api/v1/alert_channels.py): `src/monitoring/api/v1/alert_channels.py`
- [Reports API](https://github.com/mikky00b/watchdog/blob/main/src/monitoring/api/v1/reports.py): `src/monitoring/api/v1/reports.py`
- [Status page API](https://github.com/mikky00b/watchdog/blob/main/src/monitoring/api/v1/status_pages.py): `src/monitoring/api/v1/status_pages.py`

### Monitoring runtime

- [Monitor scheduler](https://github.com/mikky00b/watchdog/blob/main/src/monitoring/workers/scheduler.py): `src/monitoring/workers/scheduler.py`
- [Check execution](https://github.com/mikky00b/watchdog/blob/main/src/monitoring/services/checker_service.py): `src/monitoring/services/checker_service.py`
- [Rule evaluation](https://github.com/mikky00b/watchdog/blob/main/src/monitoring/services/rule_engine.py): `src/monitoring/services/rule_engine.py`
- [Monitor management](https://github.com/mikky00b/watchdog/blob/main/src/monitoring/services/monitor_service.py): `src/monitoring/services/monitor_service.py`

### Incident and alerting

- [Incident handling](https://github.com/mikky00b/watchdog/blob/main/src/monitoring/services/incident_service.py): `src/monitoring/services/incident_service.py`
- [Alert management](https://github.com/mikky00b/watchdog/blob/main/src/monitoring/services/alert_service.py): `src/monitoring/services/alert_service.py`
- [Notification delivery](https://github.com/mikky00b/watchdog/blob/main/src/monitoring/services/notification_service.py): `src/monitoring/services/notification_service.py`
- [Notification worker](https://github.com/mikky00b/watchdog/blob/main/src/monitoring/workers/notification_worker.py): `src/monitoring/workers/notification_worker.py`
- [Email and Telegram senders](https://github.com/mikky00b/watchdog/tree/main/src/monitoring/alerting): `src/monitoring/alerting`
- [Telegram integration](https://github.com/mikky00b/watchdog/blob/main/src/monitoring/api/v1/integrations/telegram.py): `src/monitoring/api/v1/integrations/telegram.py`

### Domain data

- [Reliability reports](https://github.com/mikky00b/watchdog/blob/main/src/monitoring/services/report_service.py): `src/monitoring/services/report_service.py`
- [Status page service](https://github.com/mikky00b/watchdog/blob/main/src/monitoring/services/status_page_service.py): `src/monitoring/services/status_page_service.py`
- [PostgreSQL data](https://github.com/mikky00b/watchdog/blob/main/src/monitoring/database.py): `src/monitoring/database.py`
- [Domain records](https://github.com/mikky00b/watchdog/tree/main/src/monitoring/models): `src/monitoring/models`

### Other components

- **Team user**

## Connections

- Team user → Web dashboard: uses (evidence: `README.md`)
- Web dashboard → API client: requests through (evidence: `frontend/src/ui/App.tsx`)
- API client → FastAPI application: calls API (evidence: `frontend/src/services.ts`)
- FastAPI application → Authentication API: routes to (evidence: `src/monitoring/main.py`)
- FastAPI application → Organization and client APIs: routes to (evidence: `src/monitoring/main.py`)
- FastAPI application → Monitor and check APIs: routes to (evidence: `src/monitoring/main.py`)
- FastAPI application → Alert channel API: routes to (evidence: `src/monitoring/main.py`)
- FastAPI application → Reports API: routes to (evidence: `src/monitoring/main.py`)
- FastAPI application → Status page API: routes to (evidence: `src/monitoring/main.py`)
- Authentication API → Identity service: delegates to (evidence: `src/monitoring/api/v1/auth.py`)
- Identity service → PostgreSQL data: reads and writes (evidence: `src/monitoring/services/auth_service.py`)
- Identity service → Email and Telegram senders: sends auth email (evidence: `src/monitoring/services/auth_service.py`)
- Monitor and check APIs → Monitor management: delegates to (evidence: `src/monitoring/services/monitor_service.py`)
- Monitor management → Check execution: runs manual checks (evidence: `src/monitoring/services/monitor_service.py`)
- Monitor scheduler → Check execution: runs scheduled checks (evidence: `src/monitoring/workers/scheduler.py`)
- Monitor scheduler → Rule evaluation: evaluates results (evidence: `src/monitoring/workers/scheduler.py`)
- Monitor scheduler → Incident handling: handles incidents (evidence: `src/monitoring/workers/scheduler.py`)
- Monitor scheduler → Alert management: creates alerts (evidence: `src/monitoring/workers/scheduler.py`)
- Check execution → PostgreSQL data: stores check results (evidence: `src/monitoring/services/checker_service.py`)
- Rule evaluation → PostgreSQL data: reads check history (evidence: `src/monitoring/services/rule_engine.py`)
- Incident handling → PostgreSQL data: stores incidents
- Alert management → PostgreSQL data: stores alerts (evidence: `src/monitoring/services/alert_service.py`)
- Alert management → Notification delivery: queues notifications (evidence: `README.md`)
- Notification worker → Notification delivery: sends pending events (evidence: `src/monitoring/workers/notification_worker.py`)
- Notification delivery → Email and Telegram senders: dispatches channels (evidence: `src/monitoring/services/notification_service.py`)
- Email and Telegram senders → Team user: delivers alerts (evidence: `README.md`)
- Telegram integration → PostgreSQL data: uses session
- Reports API → Reliability reports: generates reports
- Reliability reports → PostgreSQL data: reads monitoring history (evidence: `src/monitoring/services/report_service.py`)
- Status page API → Status page service: serves status pages
- Status page service → PostgreSQL data: reads status data
- PostgreSQL data → Domain records: persists records (evidence: `src/monitoring/database.py`)