Architecture & design decisions (v0) + open questions

[thorwhalen]

This is the living design-decision record for heed. Detail lives in
misc/docs/design.md;
the evidence behind it lives in
misc/docs/research-report.md.
This thread is for why; concrete work is tracked in issues.

What heed is

A public, no-install, embeddable way for an ordinary visitor of a deployed web app
to report a bug or request a feature — context gathered automatically — routed to a
backend the maintainer owns. It is the inverse of developer-side tools (Chrome DevTools
MCP, Jam, ov): those serve the maintainer; heed serves the maintainer's users.

Decisions (ADR-lite)

1. Two halves, one typed Report contract. A framework-agnostic widget and a
   mountable Python backend, coupled only by a Pydantic Report (SSOT in base.py).
2. Widget = tiny async loader → Web Component (open Shadow DOM) + native <dialog>.
   One embed works in React, plain HTML, and SSR. <dialog> because Radix/focus-trap
   libs break inside Shadow DOM. A thin React wrapper is convenience, not a second impl.
3. Standalone first; enlace is an optional, lazy add-on. Core has zero enlace
   import at load. Integration is heed[enlace] and mounts via include_router (not
   .mount()), injecting auth via Depends so enlace_auth binds identity when present.
4. Pluggable sinks (strategy pattern). GitHubIssuesSink is the v1 default;
   Discussions/board/email/Slack/DB are drop-in adapters. The dispatcher never branches
   on sink type.
5. Privacy by default. Screenshot + URL + env are the default; console/network/replay
   are opt-in with mandatory PII masking and a consent affordance (ePrivacy Art. 5(3)
   generally requires consent to capture replay from a stranger's device).
6. The ingest endpoint is unauthenticated and hostile. Turnstile + Redis-backed rate
   limiting + payload caps + a server-side origin/repo allowlist + a moderation queue.
   No frontend secret can authenticate it; the browser never names the target repo.
7. No GitHub token in the browser; brokered via a GitHub App. And: there is no
   GitHub API to attach an image to an issue — store the screenshot and embed its URL
   (commit-to-branch / dol blob / Release asset); base64 data-URIs do not render.
8. AI is a single structured-JSON triage call + two-stage dedup, with prompt-injection
   boundary markers on user text; the queue is exposed to Claude Code as MCP tools via
   py2mcp, sharing the same core functions as the HTTP router (SSOT).
9. Reuse, license-clean. Closest prior art is BugDrop (MIT) — study & rebuild on
   FastAPI/dol. Fork the MIT @fasterfixes/core+/mcp. Clean-room anything copyleft
   (Fider's data model, etc.) from public APIs.

Open questions (help wanted)

• Widget distribution: self-hosted CDN bundle vs npm package vs both? Embed versioning.
• Identity: heed-native anonymous id vs leaning on enlace_auth; the abuse↔friction trade.
• Board surface (Phase 3): build a native votes/roadmap board, or route feature
  requests to GitHub Discussions and treat that as the board?
• Default sink when no GitHub App is configured: store-only? email? a built-in board?

Weigh in below. When a question resolves, it becomes an issue.