# 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.