# nisfeight8/pulsewatch architecture

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

- Interactive diagram: https://gitdiagram.com/nisfeight8/pulsewatch
- Repository: https://github.com/nisfeight8/pulsewatch

## Overview

PulseWatch lets users register and manage HTTP monitors, then independently checks them, records status transitions and incidents, and presents uptime data in a dashboard. The API and checker coordinate through Redis Streams; the checker has no database access. The graph preserves the documented email-alert path and frontend polling capability. Some worker, service, and task internals are represented by their exact enclosing directories because their source was not sampled.

Main entry points: [`api/app/main.py`](https://github.com/nisfeight8/pulsewatch/blob/main/api/app/main.py) (FastAPI application), [`worker/worker/scheduler.py`](https://github.com/nisfeight8/pulsewatch/blob/main/worker/worker/scheduler.py) (Check scheduler), [`api/app/monitor`](https://github.com/nisfeight8/pulsewatch/tree/main/api/app/monitor) (Monitor management), [`api/consumer/handlers.py`](https://github.com/nisfeight8/pulsewatch/blob/main/api/consumer/handlers.py) (Status handlers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web frontend"]
  node_webapp["React application<br/>[App.tsx]"]
  node_routes["Page routing<br/>[AppRoutes.tsx]"]
  node_pages["Dashboard and detail"]
  node_queries["Polling queries"]
  node_frontend_services["API services"]
  node_api_client["HTTP client<br/>[api-client.ts]"]
end

subgraph group_api["Core API"]
  node_api_entry["FastAPI application<br/>[main.py]"]
  node_auth["Authentication"]
  node_monitor_api["Monitor management"]
  node_incident_api["Incident history"]
end

subgraph group_checker["Checker worker"]
  node_sync["Monitor sync consumer"]
  node_snapshot[("Monitor snapshot<br/>[state.py]")]
  node_scheduler["Check scheduler<br/>[scheduler.py]"]
  node_checker["HTTP checker<br/>[checker.py]"]
end

subgraph group_processing["Event processing"]
  node_status_consumer["Status event consumer"]
  node_handlers["Status handlers<br/>[handlers.py]"]
  node_email_tasks["Email alert tasks<br/>[tasks.py]"]
  node_celery["Celery worker<br/>[celery_app.py]"]
end

node_user(("Monitor user"))
node_database[("PostgreSQL")]
node_redis[("Redis Streams and broker")]
node_targets(("Monitored endpoints"))
node_mail["SMTP service"]

node_user -->|"uses"| node_webapp
node_webapp -->|"renders"| node_routes
node_routes -->|"routes to"| node_pages
node_pages -->|"requests data"| node_queries
node_queries -->|"calls"| node_frontend_services
node_frontend_services -->|"uses"| node_api_client
node_api_client -->|"REST requests"| node_api_entry
node_api_entry -->|"dispatches auth"| node_auth
node_api_entry -->|"dispatches monitors"| node_monitor_api
node_api_entry -->|"dispatches incidents"| node_incident_api
node_auth -->|"reads/writes users"| node_database
node_monitor_api -->|"reads/writes monitors"| node_database
node_monitor_api -->|"publishes monitor_events"| node_redis
node_incident_api -->|"reads incidents"| node_database
node_redis -->|"delivers monitor_events"| node_sync
node_sync -->|"updates snapshot"| node_snapshot
node_scheduler -->|"reads snapshot"| node_snapshot
node_scheduler -->|"dispatches checks"| node_checker
node_checker -->|"checks endpoints"| node_targets
node_scheduler -->|"publishes status_changes"| node_redis
node_redis -->|"delivers status_changes"| node_status_consumer
node_status_consumer -->|"dispatches events"| node_handlers
node_handlers -->|"updates status/incidents"| node_database
node_handlers -->|"queues alert task"| node_email_tasks
node_email_tasks -->|"enqueues task"| node_redis
node_redis -->|"delivers task"| node_celery
node_celery -->|"sends email"| node_mail

click node_webapp "https://github.com/nisfeight8/pulsewatch/blob/main/frontend/src/App.tsx"
click node_routes "https://github.com/nisfeight8/pulsewatch/blob/main/frontend/src/routes/AppRoutes.tsx"
click node_pages "https://github.com/nisfeight8/pulsewatch/tree/main/frontend/src/pages"
click node_queries "https://github.com/nisfeight8/pulsewatch/tree/main/frontend/src/queries"
click node_frontend_services "https://github.com/nisfeight8/pulsewatch/tree/main/frontend/src/services"
click node_api_client "https://github.com/nisfeight8/pulsewatch/blob/main/frontend/src/services/api-client.ts"
click node_api_entry "https://github.com/nisfeight8/pulsewatch/blob/main/api/app/main.py"
click node_auth "https://github.com/nisfeight8/pulsewatch/tree/main/api/app/auth"
click node_monitor_api "https://github.com/nisfeight8/pulsewatch/tree/main/api/app/monitor"
click node_incident_api "https://github.com/nisfeight8/pulsewatch/tree/main/api/app/incident"
click node_sync "https://github.com/nisfeight8/pulsewatch/tree/main/worker/worker/monitor_sync"
click node_snapshot "https://github.com/nisfeight8/pulsewatch/blob/main/worker/worker/state.py"
click node_scheduler "https://github.com/nisfeight8/pulsewatch/blob/main/worker/worker/scheduler.py"
click node_checker "https://github.com/nisfeight8/pulsewatch/blob/main/worker/worker/checker.py"
click node_status_consumer "https://github.com/nisfeight8/pulsewatch/tree/main/api/consumer"
click node_handlers "https://github.com/nisfeight8/pulsewatch/blob/main/api/consumer/handlers.py"
click node_email_tasks "https://github.com/nisfeight8/pulsewatch/blob/main/api/app/incident/tasks.py"
click node_celery "https://github.com/nisfeight8/pulsewatch/blob/main/api/app/core/celery_app.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_webapp,node_routes,node_pages,node_queries,node_frontend_services,node_api_client,node_user toneBlue
class node_api_entry,node_auth,node_monitor_api,node_incident_api,node_database,node_redis toneAmber
class node_sync,node_snapshot,node_scheduler,node_checker toneMint
class node_status_consumer,node_handlers,node_email_tasks,node_celery toneRose
class node_targets,node_mail toneIndigo
```

## Components

### Web frontend

- [React application](https://github.com/nisfeight8/pulsewatch/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Page routing](https://github.com/nisfeight8/pulsewatch/blob/main/frontend/src/routes/AppRoutes.tsx): `frontend/src/routes/AppRoutes.tsx`
- [Dashboard and detail](https://github.com/nisfeight8/pulsewatch/tree/main/frontend/src/pages): `frontend/src/pages`
- [Polling queries](https://github.com/nisfeight8/pulsewatch/tree/main/frontend/src/queries): `frontend/src/queries`
- [API services](https://github.com/nisfeight8/pulsewatch/tree/main/frontend/src/services): `frontend/src/services`
- [HTTP client](https://github.com/nisfeight8/pulsewatch/blob/main/frontend/src/services/api-client.ts): `frontend/src/services/api-client.ts`

### Core API

- [FastAPI application](https://github.com/nisfeight8/pulsewatch/blob/main/api/app/main.py): `api/app/main.py`
- [Authentication](https://github.com/nisfeight8/pulsewatch/tree/main/api/app/auth): `api/app/auth`
- [Monitor management](https://github.com/nisfeight8/pulsewatch/tree/main/api/app/monitor): `api/app/monitor`
- [Incident history](https://github.com/nisfeight8/pulsewatch/tree/main/api/app/incident): `api/app/incident`

### Checker worker

- [Monitor sync consumer](https://github.com/nisfeight8/pulsewatch/tree/main/worker/worker/monitor_sync): `worker/worker/monitor_sync`
- [Monitor snapshot](https://github.com/nisfeight8/pulsewatch/blob/main/worker/worker/state.py): `worker/worker/state.py`
- [Check scheduler](https://github.com/nisfeight8/pulsewatch/blob/main/worker/worker/scheduler.py): `worker/worker/scheduler.py`
- [HTTP checker](https://github.com/nisfeight8/pulsewatch/blob/main/worker/worker/checker.py): `worker/worker/checker.py`

### Event processing

- [Status event consumer](https://github.com/nisfeight8/pulsewatch/tree/main/api/consumer): `api/consumer`
- [Status handlers](https://github.com/nisfeight8/pulsewatch/blob/main/api/consumer/handlers.py): `api/consumer/handlers.py`
- [Email alert tasks](https://github.com/nisfeight8/pulsewatch/blob/main/api/app/incident/tasks.py): `api/app/incident/tasks.py`
- [Celery worker](https://github.com/nisfeight8/pulsewatch/blob/main/api/app/core/celery_app.py): `api/app/core/celery_app.py`

### Other components

- **Monitor user**
- **PostgreSQL**
- **Redis Streams and broker**
- **Monitored endpoints**
- **SMTP service**

## Connections

- Monitor user → React application: uses
- React application → Page routing: renders
- Page routing → Dashboard and detail: routes to
- Dashboard and detail → Polling queries: requests data
- Polling queries → API services: calls
- API services → HTTP client: uses
- HTTP client → FastAPI application: REST requests
- FastAPI application → Authentication: dispatches auth
- FastAPI application → Monitor management: dispatches monitors
- FastAPI application → Incident history: dispatches incidents
- Authentication → PostgreSQL: reads/writes users
- Monitor management → PostgreSQL: reads/writes monitors
- Monitor management → Redis Streams and broker: publishes monitor_events
- Incident history → PostgreSQL: reads incidents
- Redis Streams and broker → Monitor sync consumer: delivers monitor_events
- Monitor sync consumer → Monitor snapshot: updates snapshot
- Check scheduler → Monitor snapshot: reads snapshot
- Check scheduler → HTTP checker: dispatches checks
- HTTP checker → Monitored endpoints: checks endpoints
- Check scheduler → Redis Streams and broker: publishes status_changes
- Redis Streams and broker → Status event consumer: delivers status_changes
- Status event consumer → Status handlers: dispatches events
- Status handlers → PostgreSQL: updates status/incidents
- Status handlers → Email alert tasks: queues alert task
- Email alert tasks → Redis Streams and broker: enqueues task
- Redis Streams and broker → Celery worker: delivers task
- Celery worker → SMTP service: sends email