Signal/docs/convex-signal-instance-brief-2026-06-24.md

# Brief for Pi — Modular Convex-Based Signal Instance (Parallel Experiment)

**Date:** 2026-06-24
**From:** Claude (synthesizing Kisa's direction)
**For:** Pi (produce the build design from this brief; then Claude builds)
**Approves:** Kisa
**Status:** Design input. This is a SEPARATE, parallel instance. Nothing in the current build is abandoned or touched.

---

## 1. Objective

Design a **modular, backend-swappable architecture** for a separate "Signal on Convex" instance — an experimental alternative to the current Railway/Supabase/Vercel/Clerk stack — that exploits Convex's reactive platform and its affordable HIPAA path, while keeping the design portable enough that the backend (Convex / AWS RDS / Neon Postgres) is a config choice, not a rewrite.

This is a **parallel R&D track**, not a migration. The live Signal build keeps running and keeps being developed. This proves Convex on the real product before any commitment.

## 2. Why (strategic context)

- **Current stack** is not HIPAA-capable for real PHI (Railway has no BAA; Supabase Pro has no HIPAA tier). PHI is currently mock/synthetic and deferred. The compliance risk is latent, not active.
- **Convex (verified 2026-06-24):** reactive TypeScript backend. **BAA + HIPAA/SOC 2 reports + daily backups are on the Professional plan at $25/developer/month** — not gated behind Enterprise. SOC 2 Type II, AWS-hosted, GDPR. Built-in: server functions, crons, file storage, vector search, auth, audit log. Open-source / self-hostable. Ships **Convex Components** = independent, modular, TypeScript building blocks.
- **The prize:** one managed platform at ~$25/mo that could collapse today's patchwork (backend + DB + storage + automation + the future compliance host) into a single BAA-covered home — and avoid the AWS complexity Kisa wants to avoid.
- **The fallback (already built):** AWS — BAA signed 2026-05-27, RDS + S3 provisioned, currently parked. Proven, break-glass. Neon (managed Postgres, HIPAA on Scale, scale-to-zero) is a cheaper managed-Postgres fallback.
- **The one real risk:** Convex vendor lock-in (proprietary reactive layer). The modularity + swappable data layer below is the deliberate hedge.

## 3. Modularity requirements (Kisa's explicit ask)

Modular where it adds value and stays cohesive. **Not** so granular it's hard to build. Pragmatic seams, one coherent whole.

Required modular seams:
1. **Auth / login module** — designed behind a seam so it can be **Convex auth OR Clerk** (we already run Clerk in production). Pick a default, but keep the seam clean so swapping is config, not rewrite.
2. **Data-access layer (the keystone)** — all reads/writes go through a clean interface so the persistence backend (**Convex / AWS RDS / Neon Postgres**) is interchangeable. This is the primary lock-in hedge. Note Convex's BYOD-Postgres option as a further mitigation.
3. **Readiness-rules engine** — the gap/verdict logic as a self-contained module (reuse the existing rules-as-addressable-config direction + `payer_rules.json`), so it is portable across instances and reusable across the STTIL portfolio (and the future Med Tracker).
4. **Document / file storage module** — behind a seam (Convex file storage vs S3).
5. **Automations module** — scheduled checks / crons as discrete, named jobs.
6. **Notifications module** — new-lead / worklist alerts, swappable transport (matches existing n8n + NavBot patterns).

Use **Convex Components** where they map cleanly to these seams. Keep it cohesive — favor a small number of meaningful modules over many micro-modules.

## 4. Same architecture strategy (git / skills / workflow)

The Convex instance must fit STTIL's existing operating model, not invent a new one:
- **Git-versioned in a SEPARATE repo `signal-convex`** (Forgejo source of truth + GitHub, per the `git-push` convention; check Forgejo for an existing repo first). Decided 2026-06-24: a separate repo, NOT a directory in the existing build, so the experiment can never be confused with or break the pilot-critical live Signal repo. Shared logic (readiness rules + `payer_rules.json`) is COPIED into the spike for now; extract a shared package only if both instances graduate.
- **Pi designs → Claude builds.** Pi persists this design to a file (`design-review-persist` skill); state tracked in `context/current-state.md` via `state-sync`; design docs versioned per `research-versioning`.
- **Implements the SAME readiness model** as the current build (per `readiness-model-brief-2026-06-23.md`): plan-type is a required client-supplied field (never guessed), required-vs-supplied verdict that kills the false green, patient → device-line → shipment grouping, citations on every determination. The Convex instance re-expresses this model on Convex, it does not redesign it.
- **Compliance alignment:** rotating anonymous patient ID direction; human-in-the-loop preserved; built-in audit log; non-PHI stays out of the PHI boundary; **BAA must be signed before any real PHI touches it.** Map to the `project_signal_compliance_architecture` direction (EO on AI + identifiable health data, local inference where relevant, API-first connectors). Flag where `sttil-compliance-check` + attorney sign-off are required.

## 5. What Pi should design / deliver

1. The module map: the seams from §3, their boundaries, and how they stay cohesive (a diagram + an analogy per `feedback_analogical_explainer`).
2. The data-access interface that makes Convex / RDS / Neon swappable (the lock-in hedge), including the BYOD-Postgres note.
3. The Convex schema + function structure for the readiness model.
4. The auth seam (Convex auth vs Clerk) with a recommended default.
5. How it reuses the existing readiness logic + `payer_rules.json` rather than re-inventing it.
6. Repo structure + how it plugs into git / skills / state-sync / Pi-builds-Claude workflow.
7. Compliance touchpoints + the explicit "needs BAA / attorney / compliance-check before PHI" list.
8. A **phased, timeboxed spike plan** (prove the core readiness loop + auth seam + data-layer swappability first), sized so it does NOT eat pilot or readiness-model time.
9. Effort estimate + an explicit "what Claude builds first."

## 6. Out of scope (keep it a spike, not a rebuild)

- No real PHI until the Convex BAA is signed.
- Do not touch or migrate the existing live build.
- No full feature parity in v1 — prove the core loop + the two key seams (auth, data layer).
- No over-granular micro-modularization.
- Final PHI-backend decision (Convex vs AWS vs Neon vs "Validated Cloud") is NOT made here — this spike produces the evidence for it.

## 7. Open questions for Pi to resolve

- Convex auth vs keep Clerk as the default for the spike?
- Dedup key decision still open from the readiness model (same patient + device + DOS under two order numbers → one line or two?) — carry the same resolution here.
- Where the data-access interface boundary should sit to keep Convex's reactivity benefit while preserving swappability (the real design tension — reactivity is Convex-specific; flag honestly how much portability costs).