# koldan001/najavaradova architecture

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

- Interactive diagram: https://gitdiagram.com/koldan001/najavaradova
- Repository: https://github.com/koldan001/najavaradova

## Overview

NajavaRadova.rs turns utility outage announcements into address-level alerts and public outage information. The main workflow polls utility sources, parses and validates notices, resolves locations and matches affected addresses, then queues notifications for independent Telegram and email workers. SQLite-backed review and risk checks guard delivery; separate account, broadcast, monitoring, and public-map branches support the service. The README documents the public map and city pages, but their web source directories are absent from this tree. Some subsystem links rely on README or SOURCE INDEX references rather than sampled implementation.

Main entry points: [`core/matchmaker.py`](https://github.com/koldan001/najavaradova/blob/main/core/matchmaker.py) (Address matcher), [`scrapers`](https://github.com/koldan001/najavaradova/tree/main/scrapers) (Utility scrapers), [`core/database.py`](https://github.com/koldan001/najavaradova/blob/main/core/database.py) (SQLite database), [`main.py`](https://github.com/koldan001/najavaradova/blob/main/main.py) (Scrape cycle)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Notice ingestion"]
  node_cycle["Scrape cycle<br/>[main.py]"]
  node_scrapers["Utility scrapers"]
end

subgraph group_matching["Parsing and matching"]
  node_parser["Notice parser<br/>[parser.py]"]
  node_matcher["Address matcher<br/>[matchmaker.py]"]
  node_spatial["Spatial resolver<br/>[spatial_engine.py]"]
  node_database[("SQLite database<br/>[database.py]")]
end

subgraph group_delivery["Alerts and delivery"]
  node_sendcheck["Risk checks<br/>[send_check.py]"]
  node_review["Operator review<br/>[review.py]"]
  node_queue["Message queue<br/>[database.py]"]
  node_telegramworker["Telegram sender<br/>[telegram_worker.py]"]
  node_emailworker["Email sender<br/>[email_worker.py]"]
  node_delivery["Delivery helpers<br/>[delivery.py]"]
end

subgraph group_accounts["Accounts and operations"]
  node_auth["Accounts and auth<br/>[auth.py]"]
  node_bot["Telegram bot<br/>[telegram_bot.py]"]
  node_broadcast["City broadcasts<br/>[broadcast.py]"]
  node_watchdog["Pipeline watchdog<br/>[watchdog.py]"]
  node_health["Source health<br/>[source_health.py]"]
end

subgraph group_public["Public information"]
  node_site["City pages and map data<br/>[build_web_data.py]"]
  node_mapworker["Map data worker<br/>[worker.js]"]
end

node_utilities(("Utility sources"))
node_rgz[("RGZ registry")]
node_osm["OpenStreetMap"]
node_telegram["Telegram service"]
node_email["Email service"]
node_users(("Subscribers"))
node_cloudflare[("Cloudflare KV")]
node_gemini["Gemini API"]

node_utilities -->|"publish notices"| node_scrapers
node_cycle -->|"runs scrapers"| node_scrapers
node_scrapers -->|"parse notices"| node_parser
node_parser -->|"requests extraction"| node_gemini
node_scrapers -->|"submit notices"| node_matcher
node_matcher -->|"parses notices"| node_parser
node_matcher -->|"resolves locations"| node_spatial
node_spatial -->|"queries addresses"| node_rgz
node_spatial -.->|"fallback geocoding"| node_osm
node_matcher -->|"stores outages"| node_database
node_matcher -->|"checks risky alerts"| node_sendcheck
node_matcher -->|"queues notifications"| node_queue
node_cycle -->|"runs pending checks"| node_sendcheck
node_sendcheck -->|"releases holds"| node_queue
node_review -->|"reads review data"| node_database
node_telegramworker -->|"polls messages"| node_queue
node_emailworker -->|"polls messages"| node_queue
node_telegramworker -->|"uses delivery"| node_delivery
node_emailworker -->|"uses delivery"| node_delivery
node_telegramworker -->|"sends messages"| node_telegram
node_emailworker -->|"sends messages"| node_email
node_users -.->|"registers accounts"| node_auth
node_bot -->|"reads and updates"| node_database
node_bot -->|"supports review"| node_review
node_broadcast -->|"selects recipients"| node_database
node_watchdog -->|"checks source status"| node_health
node_watchdog -->|"alerts operator"| node_telegram
node_cycle -->|"refreshes map data"| node_site
node_site -.->|"publishes map data"| node_mapworker
node_mapworker -.->|"serves map data"| node_cloudflare

click node_cycle "https://github.com/koldan001/najavaradova/blob/main/main.py"
click node_scrapers "https://github.com/koldan001/najavaradova/tree/main/scrapers"
click node_parser "https://github.com/koldan001/najavaradova/blob/main/parser.py"
click node_matcher "https://github.com/koldan001/najavaradova/blob/main/core/matchmaker.py"
click node_spatial "https://github.com/koldan001/najavaradova/blob/main/spatial/spatial_engine.py"
click node_database "https://github.com/koldan001/najavaradova/blob/main/core/database.py"
click node_sendcheck "https://github.com/koldan001/najavaradova/blob/main/core/send_check.py"
click node_review "https://github.com/koldan001/najavaradova/blob/main/core/review.py"
click node_queue "https://github.com/koldan001/najavaradova/blob/main/core/database.py"
click node_telegramworker "https://github.com/koldan001/najavaradova/blob/main/workers/telegram_worker.py"
click node_emailworker "https://github.com/koldan001/najavaradova/blob/main/workers/email_worker.py"
click node_delivery "https://github.com/koldan001/najavaradova/blob/main/core/delivery.py"
click node_auth "https://github.com/koldan001/najavaradova/blob/main/core/auth.py"
click node_bot "https://github.com/koldan001/najavaradova/blob/main/workers/telegram_bot.py"
click node_broadcast "https://github.com/koldan001/najavaradova/blob/main/core/broadcast.py"
click node_watchdog "https://github.com/koldan001/najavaradova/blob/main/workers/watchdog.py"
click node_health "https://github.com/koldan001/najavaradova/blob/main/core/source_health.py"
click node_site "https://github.com/koldan001/najavaradova/blob/main/scripts/build_web_data.py"
click node_mapworker "https://github.com/koldan001/najavaradova/blob/main/cf/worker.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_cycle,node_scrapers toneBlue
class node_parser,node_matcher,node_spatial,node_database,node_rgz,node_cloudflare toneAmber
class node_sendcheck,node_review,node_queue,node_telegramworker,node_emailworker,node_delivery,node_gemini toneMint
class node_auth,node_bot,node_broadcast,node_watchdog,node_health toneRose
class node_site,node_mapworker,node_utilities,node_osm,node_telegram,node_email,node_users toneIndigo
```

## Components

### Notice ingestion

- [Scrape cycle](https://github.com/koldan001/najavaradova/blob/main/main.py): `main.py`
- [Utility scrapers](https://github.com/koldan001/najavaradova/tree/main/scrapers): `scrapers`

### Parsing and matching

- [Notice parser](https://github.com/koldan001/najavaradova/blob/main/parser.py): `parser.py`
- [Address matcher](https://github.com/koldan001/najavaradova/blob/main/core/matchmaker.py): `core/matchmaker.py`
- [Spatial resolver](https://github.com/koldan001/najavaradova/blob/main/spatial/spatial_engine.py): `spatial/spatial_engine.py`
- [SQLite database](https://github.com/koldan001/najavaradova/blob/main/core/database.py): `core/database.py`

### Alerts and delivery

- [Risk checks](https://github.com/koldan001/najavaradova/blob/main/core/send_check.py): `core/send_check.py`
- [Operator review](https://github.com/koldan001/najavaradova/blob/main/core/review.py): `core/review.py`
- [Message queue](https://github.com/koldan001/najavaradova/blob/main/core/database.py): `core/database.py`
- [Telegram sender](https://github.com/koldan001/najavaradova/blob/main/workers/telegram_worker.py): `workers/telegram_worker.py`
- [Email sender](https://github.com/koldan001/najavaradova/blob/main/workers/email_worker.py): `workers/email_worker.py`
- [Delivery helpers](https://github.com/koldan001/najavaradova/blob/main/core/delivery.py): `core/delivery.py`

### Accounts and operations

- [Accounts and auth](https://github.com/koldan001/najavaradova/blob/main/core/auth.py): `core/auth.py`
- [Telegram bot](https://github.com/koldan001/najavaradova/blob/main/workers/telegram_bot.py): `workers/telegram_bot.py`
- [City broadcasts](https://github.com/koldan001/najavaradova/blob/main/core/broadcast.py): `core/broadcast.py`
- [Pipeline watchdog](https://github.com/koldan001/najavaradova/blob/main/workers/watchdog.py): `workers/watchdog.py`
- [Source health](https://github.com/koldan001/najavaradova/blob/main/core/source_health.py): `core/source_health.py`

### Public information

- [City pages and map data](https://github.com/koldan001/najavaradova/blob/main/scripts/build_web_data.py): `scripts/build_web_data.py`
- [Map data worker](https://github.com/koldan001/najavaradova/blob/main/cf/worker.js): `cf/worker.js`

### Other components

- **Utility sources**
- **RGZ registry**
- **OpenStreetMap**
- **Telegram service**
- **Email service**
- **Subscribers**
- **Cloudflare KV**
- **Gemini API**

## Connections

- Utility sources → Utility scrapers: publish notices
- Scrape cycle → Utility scrapers: runs scrapers (evidence: `main.py`)
- Utility scrapers → Notice parser: parse notices (evidence: `scrapers/eps_scraper.py`)
- Notice parser → Gemini API: requests extraction
- Utility scrapers → Address matcher: submit notices (evidence: `scrapers/eps_scraper.py`)
- Address matcher → Notice parser: parses notices (evidence: `core/matchmaker.py`)
- Address matcher → Spatial resolver: resolves locations (evidence: `core/matchmaker.py`)
- Spatial resolver → RGZ registry: queries addresses
- Spatial resolver → OpenStreetMap: fallback geocoding
- Address matcher → SQLite database: stores outages (evidence: `core/matchmaker.py`)
- Address matcher → Risk checks: checks risky alerts (evidence: `core/matchmaker.py`)
- Address matcher → Message queue: queues notifications (evidence: `core/matchmaker.py`)
- Scrape cycle → Risk checks: runs pending checks (evidence: `main.py`)
- Risk checks → Message queue: releases holds (evidence: `core/send_check.py`)
- Operator review → SQLite database: reads review data (evidence: `core/review.py`)
- Telegram sender → Message queue: polls messages (evidence: `workers/telegram_worker.py`)
- Email sender → Message queue: polls messages (evidence: `workers/email_worker.py`)
- Telegram sender → Delivery helpers: uses delivery (evidence: `workers/telegram_worker.py`)
- Email sender → Delivery helpers: uses delivery (evidence: `workers/email_worker.py`)
- Telegram sender → Telegram service: sends messages
- Email sender → Email service: sends messages
- Subscribers → Accounts and auth: registers accounts
- Telegram bot → SQLite database: reads and updates (evidence: `workers/telegram_bot.py`)
- Telegram bot → Operator review: supports review (evidence: `core/review.py`)
- City broadcasts → SQLite database: selects recipients (evidence: `core/broadcast.py`)
- Pipeline watchdog → Source health: checks source status (evidence: `workers/watchdog.py`)
- Pipeline watchdog → Telegram service: alerts operator
- Scrape cycle → City pages and map data: refreshes map data
- City pages and map data → Map data worker: publishes map data
- Map data worker → Cloudflare KV: serves map data
