dare_messaging_service — architecture sketch · 2026-05-14

Parked workstream. Portfolio-portable notification micro-service: send SMS / push / email when a named report is ready to read, or when a watch-item threshold trips. Same shape as the existing publishing + sitemap pipelines — runs locally or in CI, opt-in from any script that emits a report, configured per-channel via 1Password references.

Genesis: today Dan asked, “could certain reports SMS me when ready to be read, or alerts, using Twilio, or whomever you like — its a service that runs and can be consumed.” This is the design + provider tradeoff catalogue.

What it does

A single command-line entry point any other script can call after emitting a report:

~/bin/notify-portfolio --channel sms --to dan \
    --subject "sitemap regen done" \
    --body "671 URLs, 9 non-200 image probes" \
    --link "https://devreports.dare.co.uk/dare_sitemap_regen_2026-05-14"

Decides which provider to route through based on channel + recipient config, sends the message, returns 0 on success.

The wider system is two pieces:

1. ~/bin/notify-portfolio — the synchronous send command (the “publishing service” Dan referred to). Reads provider creds from 1Password by op:// reference; routes per-channel; logs to ~/Library/Logs/dare-pipeline/notify.log.
2. Opt-in hook in report-emitting scripts — each script (dare_sitemap_regen.py, dare_404_audit.py, dare_dev_reports_publish.py, etc.) gets an optional --notify <channel:recipient> flag that calls notify-portfolio after the report lands.

The provider tradeoff (what to research before building)

Recommended channel matrix (the editorial part)

Rough guidance for which channel maps to which alert class:

Architecture sketch

                    ┌─────────────────────────────────────┐
                    │     report-emitting scripts          │
                    │  dare_sitemap_regen, dare_404_audit, │
                    │  dare_dashboard_narrator, etc.       │
                    │                                       │
                    │   each carries --notify <ch>:<who>    │
                    └──────────────┬───────────────────────┘
                                   │
                                   ▼
              ┌────────────────────────────────────────────┐
              │     ~/bin/notify-portfolio                 │
              │                                             │
              │  args: --channel sms|push|telegram|email   │
              │        --to <recipient-alias>              │
              │        --subject + --body + --link         │
              │                                             │
              │  reads:  ~/.config/notify/recipients.yaml  │
              │          ~/.config/notify/channels.yaml    │
              │  creds:  op:// from Code Shared vault       │
              │                                             │
              │  per-channel dispatcher:                    │
              │    sms  → Twilio    (op://Code Shared/...) │
              │    push → Pushover  (op://Code Shared/...) │
              │    tg   → Telegram  (op://Code Shared/...) │
              │    mail → Resend    (op://Code Shared/...) │
              │    voice → voip.ms  (op://Code Shared/...) │
              │                                             │
              │  logs:   ~/Library/Logs/dare-pipeline/      │
              │          notify.log (rotated weekly)        │
              │                                             │
              │  exit 0 on success; non-zero on send fail   │
              └────────────────────────────────────────────┘

Per-channel config shape (1Password references)

Following feedback_layered_guardrail_stack.md — every credential narrowly scoped.

# ~/.config/notify/channels.yaml
channels:
  sms:
    primary:
      provider: twilio
      account_sid:     op://Code Shared/Twilio dare-pipeline/account_sid
      auth_token:      op://Code Shared/Twilio dare-pipeline/auth_token
      from_number:     op://Code Shared/Twilio dare-pipeline/from_number
    fallback:
      provider: sms.to
      api_key:         op://Code Shared/sms.to dare-pipeline/api_key
      sender_id:       op://Code Shared/sms.to dare-pipeline/sender_id
  push:
    provider: pushover
    app_token:         op://Code Shared/Pushover dare-pipeline/app_token
    # user_key lives in recipients.yaml per-recipient
  telegram:
    provider: telegram
    bot_token:         op://Code Shared/Telegram dare-pipeline-bot/bot_token
  email:
    provider: resend
    api_key:           op://Code Shared/Resend dare-pipeline/api_key
    from_address:      noreply@dare.co.uk
  voice:
    provider: voipms
    api_username:      op://Code Shared/voip.ms dare-pipeline/api_username
    api_password:      op://Code Shared/voip.ms dare-pipeline/api_password

# ~/.config/notify/recipients.yaml
recipients:
  dan:
    phone:        op://Code Shared/Recipient dan/phone
    pushover_key: op://Code Shared/Recipient dan/pushover_user_key
    telegram_id:  op://Code Shared/Recipient dan/telegram_chat_id
    email:        op://Code Shared/Recipient dan/email

Recipient indirection allows scripts to say --to dan without ever knowing the underlying phone/email/key. Adding a second human (a client check-in) is one file entry.

Pitfalls + traps

Category A — Delivery reliability

Category B — Content shape

Category C — Recipient privacy

Category D — Cost surprise

Category E — Provider drift

Category F — Composition with other tools

Wire-up

Compounding across portfolio

Resume conditions

Build when one of these triggers: - A second report category genuinely needs out-of-band notification (today, “Dan reads devreports when he sits down” is enough for the sitemap + audit cadence; the messaging service buys nothing yet). - A cron failure case becomes load-bearing (e.g. the dashboard narrator misses a day and no one notices for hours — push-on-failure becomes worth it). - An audrey commerce alert needs SMS (high-value order, low-stock trigger) — turns push notifications into customer-facing value. - A dogwood booking flow needs the SMS confirmation tier — service quality improvement.

Until then: parked. Cross-references: feedback_park_with_resume_conditions.md.

What I’d build first (when triggered)

1. notify-portfolio CLI v1: SMS via Twilio + push via Pushover only (the two channels covering 90% of cases). YAML config; op:// for creds.
2. --notify flag on dare_sitemap_regen.py + dare_404_audit.py + dare_dashboard_refresh.sh — opt-in, off by default.
3. Self-test cron weekly per channel.
4. Watch-item escalation to push when audit thresholds tripped.
5. Telegram channel if visual previews (sitemap diff thumbnails, narrator screenshots) start mattering.

Attribution & references

• Twilio SMS API — https://www.twilio.com/docs/sms/api
• Twilio Programmable Voice — https://www.twilio.com/docs/voice
• sms.to API — https://sms.to/developer (already integrated in dare contact-form worker per CLAUDE.md)
• Pushover API — https://pushover.net/api (one-off $5 lifetime; designed for personal alerting)
• Telegram Bot API — https://core.telegram.org/bots/api (free; rich messaging)
• Resend API — https://resend.com/docs (already in portfolio — dare contact form uses RESEND_API_KEY)
• voip.ms API — https://wiki.voip.ms/article/REST_API (Dan has beta access; AI-voice callback is the unique surface)
• A2P 10DLC for US toll-free SMS — https://www.twilio.com/docs/messaging/compliance/a2p-10dlc (registration overhead pre-launch)

Internal references

• feedback_layered_guardrail_stack.md — every channel’s creds in Code Shared, narrowly-scoped
• feedback_check_devreports_before_infra_gap_analysis.md — sweep before building (no existing notify-portfolio script today)
• feedback_just_in_time_permission_grants.md — defer minting Twilio API key / Pushover app until a real workflow needs it
• feedback_save_vs_find_alignment.md — recipient indirection (alias → underlying address) is the save-vs-find principle applied to notification routing
• project_audrey_entity_twilio_* — existing Twilio setup for audrey (already-paid integration; shared account possible)
• ~/bin/cf-access — pattern for op:// credential wrapping; notify-portfolio follows the same shape

Push the report when there’s something to read. Be quiet otherwise. Wake the human only when the human’s judgement is actually required.