# 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 code-complete 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. See `M0_VERIFICATION.md` and `M1_VERIFICATION.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.