amirtheh/iran-watcher repository overview

⁠iran-watcher

Monitors X (Twitter) Filtered Stream for Iran-related news. Stores tweets in SQLite, queues through Redis, categorizes via local ONNX models, and runs LLM summarization via Ollama. Pure Go — no Python.

⁠Architecture

X Filtered Stream (SSE)
        │
        ▼
  stream.Client          ← connects, normalizes, saves raw tweet to SQLite
        │ LPUSH Task per matching action
        ▼
  Redis (iran-watcher:tasks:{action_id})
        │ BRPOP
        ▼
  worker.Manager         ← N goroutines, each independently BRPOP from ready action queues
        │
        ├─► ActionCache  ← hot-reloadable in-memory map of action_id → (Action + Pipeline)
        │
        ├─► ONNX / Ollama / Internal pipelines
        │
        ├─► SQLite (action_executions, action_execution_metadata)
        │
        ├─► Pipeline DAG edge evaluation → downstream tasks pushed to Redis
        │
        ├─► Redis (iran-watcher:failed)  ← dead-letter for failures
        │
        └─► hub.Hub → WebSocket broadcast to connected UI clients

  api.Server             ← REST API (chi), JWT-authenticated
  iran-watcher-mcp       ← MCP server (stdio + HTTP/SSE), pure Go
  cli                    ← thin Cobra CLI over the REST API

⁠Running with Docker

docker compose build
docker compose up -d
docker compose logs -f iran-watcher

⁠Configuration

Key environment variables:

⁠Tech Stack

• Go 1.25.5 — no Python anywhere
• SQLite — embedded, DELETE journal mode (NFS-safe)
• Redis — lists only (LPUSH/BRPOP)
• ONNX Runtime — local model inference
• Ollama — LLM summarization, digest, and chat
• JWT — HS256 authentication
• WebSocket — live UI updates via gorilla/websocket
• MCP — all API endpoints exposed as MCP tools

⁠Key Features

• Event-driven action system — every unit of work is a (trigger_type, action_id, context) Task in Redis; actions chain into Pipeline DAGs
• Hot-reload — activate/deactivate actions and pipelines without restart
• Reverse geocoding — self-hosted Nominatim (Iran OSM extract) with SQLite cache
• Entity tracking — auto-discovers named entities from NER output; candidates auto-promoted by confidence/frequency thresholds
• Entity connections — co-occurrence graph with BFS subgraph API
• Map view — geo-event pins colored by tweet age (blue→red heat)
• Twitter OAuth 2.0 PKCE — Retweet/Like/Quote actions
• MCP server — iran-watcher-mcp binary exposes all REST endpoints as MCP tools for Claude Code integration

⁠Source

github.com/amir-the-h/iran-watcher⁠