# broad-announce

Multi-tenant notification router. Receives alerts from many source
systems (HTTP/JSON webhooks, WebSockets, MQTT, gRPC bidi-streaming),
normalizes them, resolves recipients via `companies` → `groups` →
`individuals` + `subscriptions`, and delivers to FCM (Android),
Telegram, SMS, email, voice, Slack, MS Teams, and arbitrary outbound
webhooks.

> **Status**: M0 + M1 + M2 + M3 **shipped** 2026-06-14. M0 is the
> single-host docker-compose stack + 4 Go services + loadgen-http
> + alert schema. M1 is the end-to-end: signed webhook → broker →
> router → deliverd-fcm → fakefcmd (live-verified, 1530 deliveries
> in the loadgen burst, 0 failures). M2 is the recipient-resolution
> rules engine (source.allowed_targets + routing_rules +
> subscriptions with min_severity, quiet hours, inminent_colapse
> bypass; hard-fail on zero recipients). M3 is Telegram delivery +
> bot commands (deliverd split into per-channel binaries,
> telegramd long-polling bot with /start /subscribe /unsubscribe
> /preferences /status /mute /unmute, faketgmd fake Bot API,
> 14 deliveries in 8 sendMessage calls, 0 failures).
> See `M0_VERIFICATION.md`, `M1_VERIFICATION.md`,
> `M2_VERIFICATION.md`, `M3_VERIFICATION.md`, `M1_SMOKE_LOG.md`,
> `M2_SMOKE_LOG.md`, and `M3_SMOKE_LOG.md` for the smoke tests.
> Spec is in `SPEC.md`, diagrams in `ARCHITECTURE.md`, build log
> in `PROMPT.md`.

## v1 in one paragraph

Six Go services (`ingestd`, `routerd`, `deliverd-fcm`,
`deliverd-telegram`, `telegramd`, `admind`) wired together by NATS
JetStream. Postgres + Timescale for live data, ClickHouse for
archive, Redis for dedupe + rate limits, EMQX for MQTT. Strict
app-level multi-tenant isolation. ~5k alerts/sec on Docker
Compose, 50k/sec design ceiling for v2 K8s.

## Repo layout

```
SPEC.md             — requirements, entities, severity, retention
ARCHITECTURE.md     — diagrams, sequences, SLOs, capacity model
PROMPT.md           — build log, decisions, open questions
M0_VERIFICATION.md  — M0 smoke test (signed webhook → 202)
M1_VERIFICATION.md  — M1 smoke test (end-to-end → fakefcmd)
M2_VERIFICATION.md  — M2 smoke test (recipient resolution)
M3_VERIFICATION.md  — M3 smoke test (Telegram delivery + bot)
M1_SMOKE_LOG.md     — M1 live run results
M2_SMOKE_LOG.md     — M2 live run results
M3_SMOKE_LOG.md     — M3 live run results
docker-compose.yml  — single-host M0–M3 stack
Dockerfile          — multi-stage build for all 7 binaries
.env.example        — every BA_* knob documented
cmd/ingestd/        — HTTP POST handler (M0), other transports in M4/M5/M11
cmd/routerd/        — M2 rules engine + M3 channel union
cmd/deliverd-fcm/   — M1 FCM HTTP v1 delivery (renamed from deliverd M3)
cmd/deliverd-telegram/ — M3 Telegram Bot API delivery
cmd/telegramd/      — M3 long-polling bot loop + command handler
cmd/admind/         — scaffold + /v1/ping (M8)
loadgen/cmd/http/   — traffic generator (M0)
internal/alert/     — Alert v1 type + Validate() + Severity.Rank
internal/broker/    — NATS JetStream wrapper
internal/config/    — env-driven config
internal/dedupe/    — 60s SET NX EX + INCR
internal/ratelimit/ — per-second INCR bucket
internal/httpserver/ — /health + /metrics scaffold
internal/observability/ — slog + Prometheus
internal/postgres/  — pgxpool wrapper
internal/routing/   — Resolver (M2 rules engine, M3 channel union)
internal/telegram/  — BotClient + command parser + handler
internal/store/     — Redis + (later) Postgres
deploy/prometheus/  — prometheus.yml
migrations/         — 001–004 + seed/seed_m2/seed_m3.sql
testfakes/          — fakefcmd (M1), faketgmd (M3)
```

## License

Private. © 2026 Techno-World.