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