broad-announce/README.md

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 shipped 2026-06-13. 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 → fakefcmd (live-verified, 1530 deliveries in the loadgen burst, 0 failures). See M0_VERIFICATION.md, M1_VERIFICATION.md, and M1_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

Four Go services (ingestd, routerd, deliverd, 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)
docker-compose.yml  — single-host M0 stack
Dockerfile          — multi-stage build for all 5 binaries
.env.example        — every BA_* knob documented
cmd/ingestd/        — HTTP POST handler (M0), other transports in M4/M5/M11
cmd/routerd/        — scaffold (M2)
cmd/deliverd/       — scaffold (M3+)
cmd/admind/         — scaffold + /v1/ping (M8)
loadgen/cmd/http/   — traffic generator (M0)
internal/alert/     — Alert v1 type + Validate()
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/store/     — Redis + (later) Postgres
deploy/prometheus/  — prometheus.yml
migrations/         — (coming, M2)
testfakes/          — (coming, M3) fake-FCM, fake-Telegram, fake-SMS

License

Private. © 2026 Techno-World.