# ototot/notifier architecture

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

- Interactive diagram: https://gitdiagram.com/ototot/notifier
- Repository: https://github.com/ototot/notifier

## Overview

1. **Overall shape**
   - This is a Rust workspace with a single executable, a shared runtime crate, and four plugin crates grouped into **sources** and **destinations**.
   - The architecture is **compile-time plugin-based**, not dynamically loaded: the server is built with whichever source/destination crates are included in the workspace.

2. **Top-level runtime vs. plugins**
   - `apps/notifier-server` is the application entrypoint and HTTP service.
   - `crates/notifier-runtime` holds shared infrastructure: configuration loading/validation, SQLite-backed storage, and template rendering.
   - `plugins/sources/*` and `plugins/destinations/*` encapsulate provider-specific routing/policy logic.

3. **Primary data flow**
   - Startup loads a single config file, validates it, reconciles configured sources, and only then marks the service ready.
   - Incoming events are accepted from provider webhooks or source polling, transformed into a rendered message, persisted to SQLite, and then delivered asynchronously to a destination.
   - The service returns webhook success only after the event has been stored, so delivery is decoupled from ingestion.

4. **Ingress side: sources**
   - Supported sources are **Twitch**, **TwitCasting**, and **Nitter**.
   - Twitch and TwitCasting are webhook-driven sources that expose one configured `POST` callback path each.
   - Nitter is pull-based: it polls RSS feeds in the background and does not gate readiness on feed availability.

5. **Egress side: destinations**
   - Supported destinations are **Discord** and **Telegram**.
   - The destination plugins are thin bindings around provider SDKs (`serenity` for Discord, `teloxide` for Telegram) with routing and policy logic in the plugin crates.
   - Messages are sent as plain text in v1, with provider-specific length limits treated as permanent failures rather than being truncated.

6. **Configuration model**
   - Configuration is loaded once at startup and requires restart to change.
   - Sources and destinations are keyed reusable instances; routes reference those IDs and add route-local inputs such as broadcaster lists, channel IDs, and message templates.
   - Route IDs must remain stable across restarts because they are part of the durable routing model.

7. **Template and event shaping**
   - Route `message` fields use **MiniJinja** templates.
   - Rendering happens at webhook ingestion time, and the rendered text is what gets stored, which makes retries deterministic.
   - The runtime also exposes schema and template-variable documentation through the `schema` command.

8. **Persistence and delivery**
   - SQLite is the durable queue and state store.
   - Accepted events are persisted before success is returned; workers later consume queued rows and deliver them to destinations.
   - Rows survive restarts, so in-flight work is recovered after process failure.

9. **Retry and failure semantics**
   - Network failures, HTTP 429, and HTTP 5xx are retried with exponential backoff and jitter up to one hour.
   - Other 4xx responses and exhausted retries are moved to dead-letter state.
   - If a route is removed while rows are queued, those rows are also moved to dead-letter.

10. **Readiness and reconciliation**
   - `GET /health` and `GET /ready` are exposed by the server.
   - Readiness depends on successful source reconciliation: missing provider subscriptions are created, but absent config entries are not deleted from providers.
   - Twitch callback URLs are derived from `public_base_url` plus a source path; TwitCasting requires the full callback URL to be configured separately.

11. **Deduplication and at-least-once delivery**
   - Delivery is explicitly **at least once**; duplicate sends can occur if a destination accepts a request but the response is lost.
   - Deduplication keys differ by source: Twitch message IDs, TwitCasting broadcaster/movie-derived keys, and Nitter RSS item GUIDs or links.
   - This keeps source identity handling in the plugin layer while the runtime handles durable queuing.

12. **Operational boundaries**
   - The service does not log specs or credentials; source and destination credentials are stored literally in config.
   - `config.example.json` and the `check-config`, `schema`, and `serve` commands form the main operator workflow.
   - The CI workflow under `.github/workflows/build.yml` supports standard Rust validation (`fmt`, `clippy`, tests) around this plugin-oriented architecture.

Main entry points: [`apps/notifier-server/src/main.rs`](https://github.com/ototot/notifier/blob/main/apps/notifier-server/src/main.rs) (Notifier server), [`crates/notifier-runtime/src/config.rs`](https://github.com/ototot/notifier/blob/main/crates/notifier-runtime/src/config.rs) (Config model), [`plugins/sources/twitch/src/lib.rs`](https://github.com/ototot/notifier/blob/main/plugins/sources/twitch/src/lib.rs) (Twitch source), [`plugins/sources/twitcasting/src/lib.rs`](https://github.com/ototot/notifier/blob/main/plugins/sources/twitcasting/src/lib.rs) (TwitCasting source)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_app["App"]
  node_node_server["Notifier server<br/>http service<br/>[main.rs]"]
  node_node_health(("Health API<br/>readiness endpoint<br/>[main.rs]"))
  node_node_reconcile(("Reconciler<br/>startup sync<br/>[main.rs]"))
  node_node_ingest["Ingestion<br/>event intake<br/>[main.rs]"]
  node_node_queue["Delivery workers<br/>async dispatcher<br/>[main.rs]"]
end

subgraph group_group_runtime["Runtime"]
  node_node_runtime_lib["Runtime core<br/>shared runtime<br/>[lib.rs]"]
  node_node_config["Config model<br/>startup config<br/>[config.rs]"]
  node_node_storage[("SQLite store<br/>durable queue<br/>[storage.rs]")]
  node_node_template["Template engine<br/>message rendering<br/>[template.rs]"]
end

subgraph group_group_sources["Sources"]
  node_node_twitch["Twitch source<br/>webhook source<br/>[lib.rs]"]
  node_node_twitcasting["TwitCasting source<br/>webhook source<br/>[lib.rs]"]
  node_node_nitter["Nitter source<br/>polling source<br/>[lib.rs]"]
end

subgraph group_group_destinations["Destinations"]
  node_node_discord["Discord destination<br/>delivery plugin<br/>[lib.rs]"]
  node_node_telegram["Telegram destination<br/>delivery plugin<br/>[lib.rs]"]
end

subgraph group_group_ops["Ops"]
  node_node_schema_cmd(("Schema command<br/>cli command<br/>[main.rs]"))
  node_node_config_example["Example config<br/>sample config"]
  node_node_ci["Build CI<br/>workflow<br/>[build.yml]"]
end

node_node_server -->|"uses"| node_node_runtime_lib
node_node_server -->|"loads"| node_node_config
node_node_server -->|"persists"| node_node_storage
node_node_server -->|"renders"| node_node_template
node_node_server -->|"exposes"| node_node_health
node_node_server -->|"reconciles"| node_node_reconcile
node_node_server -->|"accepts"| node_node_ingest
node_node_server -->|"dispatches"| node_node_queue
node_node_server -->|"provides"| node_node_schema_cmd
node_node_config -->|"binds"| node_node_twitch
node_node_config -->|"binds"| node_node_twitcasting
node_node_config -->|"binds"| node_node_nitter
node_node_config -->|"binds"| node_node_discord
node_node_config -->|"binds"| node_node_telegram
node_node_ingest -->|"renders"| node_node_template
node_node_ingest -->|"stores"| node_node_storage
node_node_queue -->|"sends"| node_node_discord
node_node_queue -->|"sends"| node_node_telegram
node_node_reconcile -->|"subscribes"| node_node_twitch
node_node_reconcile -->|"configures"| node_node_twitcasting
node_node_nitter -->|"polls into"| node_node_ingest
node_node_twitch -->|"emits"| node_node_ingest
node_node_twitcasting -->|"emits"| node_node_ingest

click node_node_server "https://github.com/ototot/notifier/blob/main/apps/notifier-server/src/main.rs"
click node_node_runtime_lib "https://github.com/ototot/notifier/blob/main/crates/notifier-runtime/src/lib.rs"
click node_node_config "https://github.com/ototot/notifier/blob/main/crates/notifier-runtime/src/config.rs"
click node_node_storage "https://github.com/ototot/notifier/blob/main/crates/notifier-runtime/src/storage.rs"
click node_node_template "https://github.com/ototot/notifier/blob/main/crates/notifier-runtime/src/template.rs"
click node_node_twitch "https://github.com/ototot/notifier/blob/main/plugins/sources/twitch/src/lib.rs"
click node_node_twitcasting "https://github.com/ototot/notifier/blob/main/plugins/sources/twitcasting/src/lib.rs"
click node_node_nitter "https://github.com/ototot/notifier/blob/main/plugins/sources/nitter/src/lib.rs"
click node_node_discord "https://github.com/ototot/notifier/blob/main/plugins/destinations/discord/src/lib.rs"
click node_node_telegram "https://github.com/ototot/notifier/blob/main/plugins/destinations/telegram/src/lib.rs"
click node_node_health "https://github.com/ototot/notifier/blob/main/apps/notifier-server/src/main.rs"
click node_node_reconcile "https://github.com/ototot/notifier/blob/main/apps/notifier-server/src/main.rs"
click node_node_ingest "https://github.com/ototot/notifier/blob/main/apps/notifier-server/src/main.rs"
click node_node_queue "https://github.com/ototot/notifier/blob/main/apps/notifier-server/src/main.rs"
click node_node_schema_cmd "https://github.com/ototot/notifier/blob/main/apps/notifier-server/src/main.rs"
click node_node_config_example "https://github.com/ototot/notifier/blob/main/config.example.json"
click node_node_ci "https://github.com/ototot/notifier/blob/main/.github/workflows/build.yml"

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_node_server,node_node_health,node_node_reconcile,node_node_ingest,node_node_queue toneBlue
class node_node_runtime_lib,node_node_config,node_node_storage,node_node_template toneAmber
class node_node_twitch,node_node_twitcasting,node_node_nitter toneMint
class node_node_discord,node_node_telegram toneRose
class node_node_schema_cmd,node_node_config_example,node_node_ci toneIndigo
```

## Components

### App

Executable entrypoint and HTTP service

- [Notifier server](https://github.com/ototot/notifier/blob/main/apps/notifier-server/src/main.rs): http service · Main executable that boots the service, exposes health/readiness, and runs workers · `apps/notifier-server/src/main.rs`
- [Health API](https://github.com/ototot/notifier/blob/main/apps/notifier-server/src/main.rs): readiness endpoint · GET /health and GET /ready surface service liveness and reconciliation state · `apps/notifier-server/src/main.rs`
- [Reconciler](https://github.com/ototot/notifier/blob/main/apps/notifier-server/src/main.rs): startup sync · Ensures required source subscriptions exist before readiness is reported · `apps/notifier-server/src/main.rs`
- [Ingestion](https://github.com/ototot/notifier/blob/main/apps/notifier-server/src/main.rs): event intake · Accepts webhook or polled events, renders messages, and persists accepted rows · `apps/notifier-server/src/main.rs`
- [Delivery workers](https://github.com/ototot/notifier/blob/main/apps/notifier-server/src/main.rs): async dispatcher · Consumes queued rows and delivers them to destinations with retries and backoff · `apps/notifier-server/src/main.rs`

### Runtime

Shared config, storage, and templating

- [Runtime core](https://github.com/ototot/notifier/blob/main/crates/notifier-runtime/src/lib.rs): shared runtime · Shared runtime crate used by the server and plugins · `crates/notifier-runtime/src/lib.rs`
- [Config model](https://github.com/ototot/notifier/blob/main/crates/notifier-runtime/src/config.rs): startup config · Loads, validates, and reconciles configuration and route definitions · `crates/notifier-runtime/src/config.rs`
- [SQLite store](https://github.com/ototot/notifier/blob/main/crates/notifier-runtime/src/storage.rs): durable queue · Persistent event queue and state store for accepted notifications · `crates/notifier-runtime/src/storage.rs`
- [Template engine](https://github.com/ototot/notifier/blob/main/crates/notifier-runtime/src/template.rs): message rendering · MiniJinja-based rendering for route messages and schema docs · `crates/notifier-runtime/src/template.rs`

### Sources

Ingress plugins for provider events

- [Twitch source](https://github.com/ototot/notifier/blob/main/plugins/sources/twitch/src/lib.rs): webhook source · Webhook-driven source plugin with source-specific deduplication and callback handling · `plugins/sources/twitch/src/lib.rs`
- [TwitCasting source](https://github.com/ototot/notifier/blob/main/plugins/sources/twitcasting/src/lib.rs): webhook source · Webhook-driven source plugin with provider-specific callback and deduplication logic · `plugins/sources/twitcasting/src/lib.rs`
- [Nitter source](https://github.com/ototot/notifier/blob/main/plugins/sources/nitter/src/lib.rs): polling source · RSS polling source plugin that discovers events in the background · `plugins/sources/nitter/src/lib.rs`

### Destinations

Egress plugins for provider delivery

- [Discord destination](https://github.com/ototot/notifier/blob/main/plugins/destinations/discord/src/lib.rs): delivery plugin · Thin binding around the Discord SDK with routing and policy logic · `plugins/destinations/discord/src/lib.rs`
- [Telegram destination](https://github.com/ototot/notifier/blob/main/plugins/destinations/telegram/src/lib.rs): delivery plugin · Thin binding around the Telegram SDK with routing and policy logic · `plugins/destinations/telegram/src/lib.rs`

### Ops

Operator docs, example config, and CI

- [Schema command](https://github.com/ototot/notifier/blob/main/apps/notifier-server/src/main.rs): cli command · Operator command for schema and template-variable documentation · `apps/notifier-server/src/main.rs`
- [Example config](https://github.com/ototot/notifier/blob/main/config.example.json): sample config · Reference configuration for operators · `config.example.json`
- [Build CI](https://github.com/ototot/notifier/blob/main/.github/workflows/build.yml): workflow · Rust formatting, linting, and test validation in GitHub Actions · `.github/workflows/build.yml`

## Connections

- Notifier server → Runtime core: uses · Server depends on shared runtime services
- Notifier server → Config model: loads · Startup loads and validates config once
- Notifier server → SQLite store: persists · Accepted events are written to SQLite before success
- Notifier server → Template engine: renders · Route messages are rendered at ingestion time
- Notifier server → Health API: exposes · HTTP service exposes health and readiness endpoints
- Notifier server → Reconciler: reconciles · Startup reconciles configured sources before ready
- Notifier server → Ingestion: accepts · Ingress path accepts provider events
- Notifier server → Delivery workers: dispatches · Background workers deliver queued rows asynchronously
- Notifier server → Schema command: provides · CLI surface includes schema documentation command
- Config model → Twitch source: binds · Config maps routes to Twitch source instances
- Config model → TwitCasting source: binds · Config maps routes to TwitCasting source instances
- Config model → Nitter source: binds · Config maps routes to Nitter source instances
- Config model → Discord destination: binds · Config maps routes to Discord destination instances
- Config model → Telegram destination: binds · Config maps routes to Telegram destination instances
- Ingestion → Template engine: renders · Messages are shaped through MiniJinja templates
- Ingestion → SQLite store: stores · Rendered events are queued durably in SQLite
- Delivery workers → Discord destination: sends · Workers deliver queued messages to Discord
- Delivery workers → Telegram destination: sends · Workers deliver queued messages to Telegram
- Reconciler → Twitch source: subscribes · Ensures Twitch webhook subscriptions exist
- Reconciler → TwitCasting source: configures · Validates and preserves TwitCasting callback setup
- Nitter source → Ingestion: polls into · Background polling feeds events into ingestion
- Twitch source → Ingestion: emits · Webhook events enter the shared ingestion pipeline
- TwitCasting source → Ingestion: emits · Webhook events enter the shared ingestion pipeline
