# petersem/monocker architecture

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

- Interactive diagram: https://gitdiagram.com/petersem/monocker
- Repository: https://github.com/petersem/monocker

## Overview

Monocker polls Docker containers, applies label and state filters, detects changes, and sends alerts through one configured messaging platform. Its documented integrations include Telegram, Pushbullet, Pushover, Discord, Ntfy, Slack, Gotify, Matrix, and Apprise. The same entry point exposes health and experimental message-send endpoints. The implementation is concentrated in index.js; excerpts show polling, filtering, several provider calls, and endpoint behavior, but omit some dispatcher and state-processing code, so those links are limited to what is documented or excerpted.

Main entry points: [`index.js`](https://github.com/petersem/monocker/blob/master/index.js) (Alert dispatch)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_monitoring["Container monitoring"]
  node_poller["Container polling<br/>[index.js]"]
  node_filters["Container selection<br/>[index.js]"]
  node_state["State change detection<br/>[index.js]"]
end

subgraph group_delivery["Alert delivery"]
  node_message["Alert dispatch<br/>[index.js]"]
  node_telegram["Telegram<br/>[index.js]"]
  node_pushbullet["Pushbullet<br/>[index.js]"]
  node_pushover["Pushover<br/>[index.js]"]
  node_discord["Discord<br/>[index.js]"]
  node_ntfy["Ntfy<br/>[index.js]"]
  node_slack["Slack<br/>[index.js]"]
  node_gotify["Gotify<br/>[index.js]"]
  node_matrix["Matrix<br/>[index.js]"]
  node_apprise["Apprise<br/>[index.js]"]
end

subgraph group_api["HTTP endpoints"]
  node_http_api["HTTP API<br/>[index.js]"]
end

node_operator(("Operator"))
node_docker[("Docker daemon")]
node_messaging_service(("Messaging services"))
node_health_client(("Health-check client"))

node_operator -.->|"configures"| node_poller
node_poller -->|"lists containers"| node_docker
node_poller -.->|"filters containers"| node_filters
node_filters -.->|"selects monitored"| node_state
node_poller -->|"detects changes"| node_state
node_state -->|"sends alerts"| node_message
node_http_api -->|"accepts send requests"| node_message
node_operator -.->|"sends request"| node_http_api
node_health_client -->|"checks status"| node_http_api
node_message -.->|"dispatches to"| node_telegram
node_message -.->|"dispatches to"| node_pushbullet
node_message -.->|"dispatches to"| node_pushover
node_message -.->|"dispatches to"| node_discord
node_message -.->|"dispatches to"| node_ntfy
node_message -.->|"dispatches to"| node_slack
node_message -.->|"dispatches to"| node_gotify
node_message -.->|"dispatches to"| node_matrix
node_message -.->|"dispatches to"| node_apprise
node_telegram -->|"sends alert"| node_messaging_service
node_pushbullet -->|"sends alert"| node_messaging_service
node_pushover -->|"sends alert"| node_messaging_service
node_discord -->|"sends alert"| node_messaging_service
node_ntfy -->|"publishes alert"| node_messaging_service
node_slack -->|"posts alert"| node_messaging_service
node_gotify -->|"sends alert"| node_messaging_service
node_matrix -->|"sends alert"| node_messaging_service
node_apprise -->|"posts alert"| node_messaging_service

click node_poller "https://github.com/petersem/monocker/blob/master/index.js"
click node_filters "https://github.com/petersem/monocker/blob/master/index.js"
click node_state "https://github.com/petersem/monocker/blob/master/index.js"
click node_message "https://github.com/petersem/monocker/blob/master/index.js"
click node_telegram "https://github.com/petersem/monocker/blob/master/index.js"
click node_pushbullet "https://github.com/petersem/monocker/blob/master/index.js"
click node_pushover "https://github.com/petersem/monocker/blob/master/index.js"
click node_discord "https://github.com/petersem/monocker/blob/master/index.js"
click node_ntfy "https://github.com/petersem/monocker/blob/master/index.js"
click node_slack "https://github.com/petersem/monocker/blob/master/index.js"
click node_gotify "https://github.com/petersem/monocker/blob/master/index.js"
click node_matrix "https://github.com/petersem/monocker/blob/master/index.js"
click node_apprise "https://github.com/petersem/monocker/blob/master/index.js"
click node_http_api "https://github.com/petersem/monocker/blob/master/index.js"

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_poller,node_filters,node_state,node_health_client toneBlue
class node_message,node_telegram,node_pushbullet,node_pushover,node_discord,node_ntfy,node_slack,node_gotify,node_matrix,node_apprise,node_docker toneAmber
class node_http_api toneMint
class node_operator,node_messaging_service toneIndigo
```

## Components

### Container monitoring

- [Container polling](https://github.com/petersem/monocker/blob/master/index.js): `index.js`
- [Container selection](https://github.com/petersem/monocker/blob/master/index.js): `index.js`
- [State change detection](https://github.com/petersem/monocker/blob/master/index.js): `index.js`

### Alert delivery

- [Alert dispatch](https://github.com/petersem/monocker/blob/master/index.js): `index.js`
- [Telegram](https://github.com/petersem/monocker/blob/master/index.js): `index.js`
- [Pushbullet](https://github.com/petersem/monocker/blob/master/index.js): `index.js`
- [Pushover](https://github.com/petersem/monocker/blob/master/index.js): `index.js`
- [Discord](https://github.com/petersem/monocker/blob/master/index.js): `index.js`
- [Ntfy](https://github.com/petersem/monocker/blob/master/index.js): `index.js`
- [Slack](https://github.com/petersem/monocker/blob/master/index.js): `index.js`
- [Gotify](https://github.com/petersem/monocker/blob/master/index.js): `index.js`
- [Matrix](https://github.com/petersem/monocker/blob/master/index.js): `index.js`
- [Apprise](https://github.com/petersem/monocker/blob/master/index.js): `index.js`

### HTTP endpoints

- [HTTP API](https://github.com/petersem/monocker/blob/master/index.js): `index.js`

### Other components

- **Operator**
- **Docker daemon**
- **Messaging services**
- **Health-check client**

## Connections

- Operator → Container polling: configures (evidence: `README.md`)
- Container polling → Docker daemon: lists containers (evidence: `index.js`)
- Container polling → Container selection: filters containers (evidence: `README.md`)
- Container selection → State change detection: selects monitored (evidence: `README.md`)
- Container polling → State change detection: detects changes (evidence: `index.js`)
- State change detection → Alert dispatch: sends alerts (evidence: `index.js`)
- HTTP API → Alert dispatch: accepts send requests (evidence: `index.js`)
- Operator → HTTP API: sends request (evidence: `index.js`)
- Health-check client → HTTP API: checks status (evidence: `index.js`)
- Alert dispatch → Telegram: dispatches to (evidence: `README.md`)
- Alert dispatch → Pushbullet: dispatches to (evidence: `README.md`)
- Alert dispatch → Pushover: dispatches to (evidence: `README.md`)
- Alert dispatch → Discord: dispatches to (evidence: `README.md`)
- Alert dispatch → Ntfy: dispatches to (evidence: `README.md`)
- Alert dispatch → Slack: dispatches to (evidence: `README.md`)
- Alert dispatch → Gotify: dispatches to (evidence: `README.md`)
- Alert dispatch → Matrix: dispatches to (evidence: `README.md`)
- Alert dispatch → Apprise: dispatches to (evidence: `README.md`)
- Telegram → Messaging services: sends alert (evidence: `index.js`)
- Pushbullet → Messaging services: sends alert (evidence: `index.js`)
- Pushover → Messaging services: sends alert (evidence: `index.js`)
- Discord → Messaging services: sends alert (evidence: `index.js`)
- Ntfy → Messaging services: publishes alert (evidence: `index.js`)
- Slack → Messaging services: posts alert (evidence: `index.js`)
- Gotify → Messaging services: sends alert (evidence: `index.js`)
- Matrix → Messaging services: sends alert (evidence: `index.js`)
- Apprise → Messaging services: posts alert (evidence: `index.js`)
