Broad-Announce — Build Log (PROMPT)

Decisions, lessons, blockers. Append-only. Update as we go.

2026-06-13 — kickoff

Decided

Repo at git3.techno-world.net/lrosales/broad-announce (private).
v1 stack: Go, PostgreSQL + Timescale, ClickHouse, NATS JetStream, Redis, EMQX (MQTT), Prometheus + Grafana, Loki. Deploy v1 = Docker Compose. v2 = K8s.
Multi-tenancy = shared infrastructure, strict app-level isolation. No row-level security in v1; tenant filter on every query.
FCM = single shared project for v1, schema supports per-company FCM project later (companies.fcm_shared).
Telegram is a first-class delivery channel + a management UI (the bot is how users mute, subscribe, acknowledge).
Severity taxonomy: info | warning | critical | inminent_colapse. Only inminent_colapse bypasses quiet hours.
Dedupe: 60s window per (source_id, dedupe_key), attach dedupe_count so user sees "×N in 60s" not N pushes.
v1 capacity target in docker-compose: 5k alerts/sec sustained. 50k/sec is the design ceiling; the K8s + multi-broker work is what unlocks it.

Open

Bot ↔ individual linking: need a clean flow. The current plan is user runs /start <email_or_phone> and we match against individuals.email / phone_e164. Open question: do we let unknown users self-register via the bot, or do we require an admin to create the individuals row first? Toward stricter is better (admin invites, bot confirms).
Localized titles: we need a title_key / body_key model, or accept pre-localized strings per-recipient from the source. Starting simple: source sends a single title/body; we do not localize in v1. If a customer needs localization, they send the alert multiple times (one per locale) keyed on subscriptions.locale. Re-evaluate at v2.
mTLS: schema supports it, but the docker-compose profile won't terminate client certs in v1. Documented as opt-in for enterprise sources.

Lessons (already)

It's much cheaper to answer "what can this be?" with 30 questions than to refactor later. Most of the SPEC's weight is in §11 (security) and §6 (recipient resolution) — those are the parts that are expensive to change after launch.
For multi-tenant at 10k companies, the one design choice that compounds is the subject layout in the broker. alerts.<company_id> is fine; alerts.<company_id>.<source_id> would let us scale router consumer groups per source. Locked in §5 of ARCHITECTURE.md.