# wispayr/protect-night-watch architecture

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

- Interactive diagram: https://gitdiagram.com/wispayr/protect-night-watch
- Repository: https://github.com/wispayr/protect-night-watch

## Overview

protect-night-watch is a scheduled or one-shot overnight UniFi Protect reporting tool. Its main workflow is to define a timezone-aware night window, fetch and filter smart-detection events, cluster them into incidents, render a PDF with optional stills, save it, and email it. The graph includes the CLI/check paths and offline demo capability. Edges reflect shown calls or documented behavior; unsampled details, including precise persistence and scheduling internals, are not inferred.

Main entry points: [`src/run.ts`](https://github.com/wispayr/protect-night-watch/blob/main/src/run.ts) (Run coordinator), [`src/index.ts`](https://github.com/wispayr/protect-night-watch/blob/main/src/index.ts) (CLI and scheduler), [`src/mail/mailer.ts`](https://github.com/wispayr/protect-night-watch/blob/main/src/mail/mailer.ts) (Email delivery), [`src/protect/client.ts`](https://github.com/wispayr/protect-night-watch/blob/main/src/protect/client.ts) (Protect client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry and configuration"]
  node_cli["CLI and scheduler<br/>[index.ts]"]
  node_config["Configuration<br/>[config.ts]"]
  node_logger["Logging<br/>[logger.ts]"]
  node_runner["Run coordinator<br/>[run.ts]"]
end

subgraph group_protect["Protect data"]
  node_protect["Protect client<br/>[client.ts]"]
  node_controller{{"UniFi Protect"}}
  node_domain["Detection and incident models<br/>[types.ts]"]
  node_demo["Synthetic report data<br/>[demo.ts]"]
end

subgraph group_report["Report generation"]
  node_window["Night window<br/>[window.ts]"]
  node_aggregate["Filter and aggregate<br/>[aggregate.ts]"]
  node_pdf["PDF renderer<br/>[pdf.ts]"]
end

subgraph group_delivery["Delivery"]
  node_pdfstore[("PDF output and retention<br/>[run.ts]")]
  node_mailer["Email delivery<br/>[mailer.ts]"]
  node_smtp{{"SMTP service"}}
end

node_operator(("Operator"))

node_operator -->|"invokes"| node_cli
node_cli -->|"loads"| node_config
node_cli -->|"runs"| node_runner
node_cli -->|"checks"| node_protect
node_cli -->|"verifies"| node_mailer
node_cli -->|"checks window"| node_window
node_cli -->|"sets level"| node_logger
node_runner -->|"builds window"| node_window
node_runner -->|"fetches events"| node_protect
node_protect -->|"queries API"| node_controller
node_runner -->|"filters and clusters"| node_aggregate
node_runner -->|"renders report"| node_pdf
node_runner -->|"fetches stills"| node_protect
node_runner -->|"uses synthetic data"| node_demo
node_runner -->|"writes and prunes"| node_pdfstore
node_runner -->|"sends report"| node_mailer
node_mailer -->|"sends email"| node_smtp
node_pdf -->|"formats times"| node_window
node_mailer -->|"formats times"| node_window
node_cli -->|"logs status"| node_logger

click node_cli "https://github.com/wispayr/protect-night-watch/blob/main/src/index.ts"
click node_config "https://github.com/wispayr/protect-night-watch/blob/main/src/config.ts"
click node_logger "https://github.com/wispayr/protect-night-watch/blob/main/src/logger.ts"
click node_runner "https://github.com/wispayr/protect-night-watch/blob/main/src/run.ts"
click node_window "https://github.com/wispayr/protect-night-watch/blob/main/src/report/window.ts"
click node_protect "https://github.com/wispayr/protect-night-watch/blob/main/src/protect/client.ts"
click node_domain "https://github.com/wispayr/protect-night-watch/blob/main/src/protect/types.ts"
click node_demo "https://github.com/wispayr/protect-night-watch/blob/main/src/demo.ts"
click node_aggregate "https://github.com/wispayr/protect-night-watch/blob/main/src/report/aggregate.ts"
click node_pdf "https://github.com/wispayr/protect-night-watch/blob/main/src/report/pdf.ts"
click node_pdfstore "https://github.com/wispayr/protect-night-watch/blob/main/src/run.ts"
click node_mailer "https://github.com/wispayr/protect-night-watch/blob/main/src/mail/mailer.ts"

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_cli,node_config,node_logger,node_runner toneBlue
class node_protect,node_controller,node_domain,node_demo toneAmber
class node_window,node_aggregate,node_pdf toneMint
class node_pdfstore,node_mailer,node_smtp toneRose
class node_operator toneIndigo
```

## Components

### Entry and configuration

- [CLI and scheduler](https://github.com/wispayr/protect-night-watch/blob/main/src/index.ts): `src/index.ts`
- [Configuration](https://github.com/wispayr/protect-night-watch/blob/main/src/config.ts): `src/config.ts`
- [Logging](https://github.com/wispayr/protect-night-watch/blob/main/src/logger.ts): `src/logger.ts`
- [Run coordinator](https://github.com/wispayr/protect-night-watch/blob/main/src/run.ts): `src/run.ts`

### Protect data

- [Protect client](https://github.com/wispayr/protect-night-watch/blob/main/src/protect/client.ts): `src/protect/client.ts`
- **UniFi Protect**
- [Detection and incident models](https://github.com/wispayr/protect-night-watch/blob/main/src/protect/types.ts): `src/protect/types.ts`
- [Synthetic report data](https://github.com/wispayr/protect-night-watch/blob/main/src/demo.ts): `src/demo.ts`

### Report generation

- [Night window](https://github.com/wispayr/protect-night-watch/blob/main/src/report/window.ts): `src/report/window.ts`
- [Filter and aggregate](https://github.com/wispayr/protect-night-watch/blob/main/src/report/aggregate.ts): `src/report/aggregate.ts`
- [PDF renderer](https://github.com/wispayr/protect-night-watch/blob/main/src/report/pdf.ts): `src/report/pdf.ts`

### Delivery

- [PDF output and retention](https://github.com/wispayr/protect-night-watch/blob/main/src/run.ts): `src/run.ts`
- [Email delivery](https://github.com/wispayr/protect-night-watch/blob/main/src/mail/mailer.ts): `src/mail/mailer.ts`
- **SMTP service**

### Other components

- **Operator**

## Connections

- Operator → CLI and scheduler: invokes (evidence: `README.md`)
- CLI and scheduler → Configuration: loads (evidence: `src/index.ts`)
- CLI and scheduler → Run coordinator: runs (evidence: `src/index.ts`)
- CLI and scheduler → Protect client: checks (evidence: `src/index.ts`)
- CLI and scheduler → Email delivery: verifies (evidence: `src/index.ts`)
- CLI and scheduler → Night window: checks window (evidence: `src/index.ts`)
- CLI and scheduler → Logging: sets level (evidence: `src/index.ts`)
- Run coordinator → Night window: builds window (evidence: `src/run.ts`)
- Run coordinator → Protect client: fetches events (evidence: `src/run.ts`)
- Protect client → UniFi Protect: queries API (evidence: `src/protect/client.ts`)
- Run coordinator → Filter and aggregate: filters and clusters (evidence: `src/run.ts`)
- Run coordinator → PDF renderer: renders report (evidence: `src/run.ts`)
- Run coordinator → Protect client: fetches stills (evidence: `src/run.ts`)
- Run coordinator → Synthetic report data: uses synthetic data (evidence: `src/run.ts`)
- Run coordinator → PDF output and retention: writes and prunes (evidence: `src/run.ts`)
- Run coordinator → Email delivery: sends report (evidence: `src/run.ts`)
- Email delivery → SMTP service: sends email (evidence: `src/mail/mailer.ts`)
- PDF renderer → Night window: formats times (evidence: `src/report/pdf.ts`)
- Email delivery → Night window: formats times (evidence: `src/mail/mailer.ts`)
- CLI and scheduler → Logging: logs status (evidence: `src/index.ts`)
