Welliva
Platform architecture briefing
Living document · July 2026

One platform, three apps,
and a clinician in the loop.

This page is the technical plan for the Welliva MVP, written for everyone on the team — not just engineers. It covers what we've decided and why, how the pieces fit together, and — most importantly — six open decisions we need to make together. Click anything that looks clickable; every section starts plain and lets you dig deeper.

01 · Executive summary

Where we are, and what we're deciding

✓ Done

Design & data model

The v2.1 animated UX prototype defines the patient app end to end. The data model is mapped: ~70 tables across 12 domains. The full architecture is agreed and documented.

● Up next

Milestone 0 — scaffold

Stand up the codebase: backend, both apps, the fake practice-records system, and the plumbing that keeps all three codebases speaking the same language.

→ To decide together

Align & decide

Confirm the plan, and settle the six amber decisions below — or explicitly agree when each will be decided and by whom.

What we're building

Three audiences, three apps, one shared platform behind them.

✦

Patients mobile app

A conversational health companion — no forms, no dashboards. It listens, notices patterns, and offers insights that a real clinician has approved. This is the app the prototype demonstrates.

◎

Practitioners web app

Where clinicians review and approve everything the AI drafts, prepare visits, and prescribe practices. They keep their own patient-records system; we connect to it.

▦

Employers web app

Aggregate engagement and outcomes only. The system is built so employer accounts cannot reach individual health data — a structural wall, not a policy.

How to use this page

  1. Start here and at the system map for the big picture — every box on the map explains itself when clicked.
  2. Decisions made — the reasoning is one click deep on every card; questions and pushback welcome.
  3. Open decisions — read the options, tap a leaning. This is the part we settle together.
  4. Roadmap and design backlog show what gets built when, and what still needs design.

From the v2.1 prototype — the patient experience everything below exists to serve. The full animated walkthrough is in docs/.

Six decisions we've locked in

Each card expands with the reasoning. The full list, with alternatives we considered, is in Decisions made.

Backend

Laravel + PostgreSQL
Velocity through opinionation: Laravel ships auth, background jobs, security, and encryption first-party, all designed to work together — nothing to assemble, no integration choices to get wrong. PostgreSQL wins for how well it stores and searches the AI's structured output, and it supports vector search later if the companion needs memory.
Codebase

One repo, shared API contract
All apps live in one repository. The backend publishes a machine-readable description of its API, and both frontends generate their code from it — so when the backend changes shape, the mobile and web apps fail loudly at build time instead of quietly in a user's hands.
Mobile

React Native via Expo
One codebase for iPhone and Android. Expo removes the most painful parts (native build tooling) and its cloud service builds the app for TestFlight without anyone installing Xcode. Daily development happens live on a real phone.
Hosting

Prototype first, DigitalOcean
We deliberately do not start on heavyweight cloud infrastructure. The whole MVP runs on a simple, cheap server — effectively a long-lived staging environment — so we learn what we don't know before committing. Two hard rules make this safe: nothing platform-specific in the code, and fictional data only. Real patient data triggers the move to compliant hosting.
EHR strategy

Sandbox EHR speaking FHIR
Practitioners keep their own records systems (EHRs). Until we integrate with a real one, we run our own miniature fake EHR for development — behind the same industry-standard data format (FHIR) real systems use. Connecting a real EHR later becomes a swap, not a rebuild.
AI safety

Clinician review gate
Nothing the AI writes reaches a patient until a practitioner approves it. This is enforced in the data model itself — an insight literally cannot be shown until its review record says "approved." It's the product's trust promise ("✓ Reviewed by Dr. Reyes") made structural.

02 · How it fits together

The system in one picture

Click any box to read what it is, what it does, and — if you want it — the technical detail underneath.

one shared, auto-generated connection layer keeps all three in sync with the platform
the platform talks outward to two things

03 · Decisions made

What we've settled, and what we turned down

These are made calls — but challenges are welcome while we're still pre-code. Each one shows the reasoning and the alternative we considered.

Backend

Laravel 12 as the platform framework

+

Why

Velocity. Laravel is an opinionated, batteries-included framework: authentication, background job queues (which power the AI pipelines), security policies, encryption, and scheduling all ship first-party and are designed to work together. There's nothing to assemble and no integration choices to get wrong — we spend our time building product, not plumbing.

What we considered

A Node/TypeScript backend (one language everywhere). Rejected: that stack is assembled from independently chosen libraries, and every choice — ORM, auth, queues, validation — is a compatibility risk that compounds over time. Our generated API contract already bridges the languages, so symmetry buys little.

Database

PostgreSQL over MySQL

+

Why

The AI pipeline stores rich structured output (extracted facts, evidence trails, model runs). Postgres indexes and queries inside that data natively, and its vector-search extension is there if the companion later needs semantic memory. Everything we might host on supports it.

What we considered

MySQL — a perfectly capable default, and Laravel treats both engines identically. Postgres won on merit: richer querying inside JSON documents, the vector-search extension, and first-class support on every host we might land on.

Codebase

One repository for everything

+

Why

Backend, web app, mobile app, and the sandbox EHR live side by side. A change that touches the API and both frontends is one change, reviewed once. New teammates clone one thing.

What we considered

Separate repositories per app. This codebase is deliberately a proof of concept: while the API contract is evolving daily, a single repository keeps every cross-cutting change atomic and reviewed once. When the product matures to where independent versioning and deploy cadences pay for themselves, splitting repos is a well-understood, low-risk move — we'll make it then, intentionally.

Contract

Auto-generated API client for both frontends

+

Why

The backend describes its own API in a machine-readable spec (via a free package called Scribe); a generator turns that into the exact code the web and mobile apps use to call it. If the backend changes a field, both apps break at build time — drift becomes impossible to miss.

What we considered

Hand-written API calls in each app — the default in most codebases, and the reason "works on web, crashes on mobile" bugs exist.

Mobile

Expo (managed React Native) + EAS builds

+

Why

One codebase for both platforms; daily development live on a real phone via Expo Go with no build step; cloud builds for TestFlight without local Xcode or Android Studio. Nothing in the prototype needs capabilities Expo lacks.

What we considered

"Bare" React Native or native Swift/Kotlin apps — more control we don't need yet, at 2–3× the build-and-maintain cost.

Local dev

No Docker — native tools (Herd + DBngin)

+

Why

For a small Mac-based team, two free menu-bar apps replace the whole container stack: Herd serves the Laravel apps, DBngin runs Postgres and Redis with an on/off toggle. Faster, nothing to babysit. Fallback if Herd misbehaves: Laravel's built-in dev server. Settled for real during Milestone 0 setup.

What we considered

Docker — real value is environment parity across a bigger team; revisit if the team grows.

Hosting

Prototype first: DigitalOcean, not AWS

+

Why

Day-one hyperscaler setups are a classic startup self-wound — weeks of infrastructure work that teaches nothing about the product. The MVP runs on a simple managed server (via Laravel Forge): cheap, boring, fast to deploy, and where we learn queue behavior, AI costs, and real load shape before committing. Two non-negotiables make it safe: nothing platform-proprietary in the code (the move later is a redeploy, not a re-architecture), and fictional data only — the first real patient record, not scale, triggers migration to compliant hosting. DigitalOcean cannot legally hold real patient data (it won't sign the required HIPAA contract), which makes the boundary conveniently unambiguous.

What we considered

Starting on AWS with HIPAA controls from day one — maximum future-proofing, weeks of drag, and we'd configure it blind. We'll configure production hosting once, informed by everything the prototype taught us.

EHR

Sandbox EHR as a separate service, speaking FHIR

+

Why

Practitioners keep their real records systems; we integrate. Until then, a miniature fake EHR (fictional patients, appointments, availability) runs as its own service behind real network calls — so timeouts, handshakes, and partial data are rehearsed from day one. Its data format is a simplified slice of FHIR, the standard real EHRs speak, so a real integration later is a driver swap. It lives in the same repository: the isolation that matters is the network boundary, not the folder structure.

What we considered

Faking the EHR inside the backend (too cozy — rehearses nothing) or a separate repository (isolation theater that doubles coordination on every contract change).

AI safety

Review gate: draft → pending → approved

+

Why

Every AI-drafted insight and visit brief moves through a review state machine, and the patient-facing API can only return approved items. The "✓ Reviewed by Dr. Reyes" stamp in the prototype isn't a label — it's the visible end of this pipeline. Every AI run is logged with its inputs and outputs, and every insight links to the underlying evidence.

What we considered

A simple "reviewed" checkbox — invites shortcuts and can't answer "who approved what, when, based on which evidence" when a regulator or partner asks.

Privacy

Employer wall + audit trail from day one

+

Why

Employer accounts enter through their own doorway that can only reach aggregate reporting code — there is no code path from an employer login to an individual's health data. Separately, every read of health data by anyone is written to an audit log from the first line of code, because retrofitting audit trails is one of the most expensive things in health software.

What we considered

Enforcing "employers see no health data" by convention and code review. Conventions erode; walls don't.

04 · Open decisions

Six decisions to make together

Amber means undecided. Each card explains the question in plain terms, lays out the options with honest pros and cons, and marks a recommendation where there is one. Tap an option to record the team's leaning — choices save in this browser, so the current leanings stay visible as this document evolves.

⚖Not everything must be settled at once — each card shows when it must be decided. The goal is a leaning on each, or an owner and a date.0 of 6 leanings recorded
1

Do we take payments in the MVP?

When a patient books a practitioner, does money move through us?

 Decide before M1

Why it matters: the booking flow is Milestone 1 — the first thing we build after the scaffold. Payments touch refunds, no-show policy, payouts to practices, and financial compliance; whichever way we go shapes weeks of work. The prototype hand-waves this ("Confirm & continue"), so the demo doesn't answer it for us.

Interacts with: employer benefits story, practice onboarding pitch.
2

How does voice input work?

The prototype leads with a microphone. What's actually behind it?

 Decide by M2

Why it matters: "talk instead of type" is the product's core promise — the whole pitch is that logging disappears into conversation. But speech-to-text can run three very different ways, with very different privacy, cost, and quality profiles.

Interacts with: compliance timing (server audio = earlier vendor agreements).
3

Which real EHR do we integrate first?

Our sandbox stands in for one — but whose system is it standing in for?

 Settle in M1–M2

Why it matters: the sandbox EHR speaks generic FHIR (the industry-standard format), which keeps options open. But real systems differ in what they expose, and the practitioners we're courting (naturopathic, integrative) cluster on a handful of platforms — Cerbo, Practice Better, OptiMantra. The first real integration will reshape the sandbox's fidelity and our sales pitch.

Either way: recruiting design-partner practitioners is a near-term action item — the review queue (Milestone 2) needs their input too.
4

How do we run the AI once real patient data flows?

Two compliant paths to the same Claude models.

 Pre-launch · awareness only

Why it matters: during the MVP (fictional data), we call the Claude API directly and simply. Once real patient conversations flow, the AI vendor must be under a HIPAA business-associate agreement (BAA). There are two routes, and the right one depends on where production ends up hosted — so this decision is deliberately coupled to #5.

Interacts with: #5. If AWS wins there, Bedrock becomes natural here. Nothing to do yet beyond awareness.
5

Where does production live at go-live?

The planned migration off DigitalOcean, when real patient data arrives.

 Pre-launch · awareness only

Why it matters: our prototype host can't sign the HIPAA contract real patient data requires, so go-live includes a hosting move — planned, budgeted, and triggered by the first real patient record. The question is destination. Because we've kept the stack deliberately portable, this is a redeploy either way.

Interacts with: #4, compliance-automation tooling (Vanta/Drata) which arrives at the same moment. Nothing to do yet.
6

One web app or two?

Practitioners and employers both use the web — same app, or separate builds?

 Decide by M2 start

Why it matters: the practitioner web app starts in Milestone 2 (the review queue is a hard dependency of the insight loop). Whether the employer portal shares its codebase determines project structure now, even though employer features come last.

Interacts with: Milestone 0 scaffold layout (mild — easy to restructure before M2).

05 · Roadmap

Five milestones, mapped to the prototype

Each milestone delivers a walkable slice of the product. The screen names reference the v2.1 prototype — the build follows the demo, and the demo is the spec.

Milestone 1prototype: Welcome → First conversation → Care match

The patient spine

A new member signs up, verifies employer eligibility, consents, has the chip-and-free-text first conversation, gets matched to a practitioner with the reasoning shown, and books a real slot from the sandbox EHR's availability. Includes the intake extraction pipeline — the first AI in production code. Also the first stretch of UX the prototype doesn't cover: sign-in, eligibility, consent screens.

Milestone 2prototype: Insight home · Invisible logging · Insight card highest risk — build first, polish later

The insight loop — the heart of the product

Members chat with the companion; the AI extracts facts silently and drafts insights with evidence; practitioners approve or reject them in the first version of the review queue (the practitioner web app is born here); approved insights land on the Insight home with the reflection sparkline. This milestone answers the existential question: does the loop actually produce insights a clinician will sign? Everything else is execution; this is discovery.

Milestone 3prototype: Connect · Records · Practices

The care surface

Care team, next session with its AI-drafted visit brief, curated records (briefs and care plans, never raw clinical notes), prescribed practices with the practice player, and completions feeding back into the insight engine.

Milestone 4prototype: locked Health-rewards card

Employer portal & rewards

Aggregate engagement and outcome dashboards for employers — behind the structural wall — plus the rewards progression and unlock. Deliberately last: lots of tables, little risk, and it needs real usage data to mean anything.

06 · Trust & compliance

How the AI stays safe, and how HIPAA gets handled

Every AI output passes a human gate

This is the product's trust promise, enforced in the data model — the patient-facing system is physically unable to show an unapproved insight.

1 · Listen

The member talks

Chat or voice. No forms, no trackers — conversation is the interface.

2 · Draft

The AI extracts & drafts

Facts written to the health record; patterns drafted as insights, every claim linked to its evidence. Every AI run is logged.

3 · The gate

A clinician reviews

Approve or reject, in the practitioner app. Nothing skips this step — not insights, not visit briefs.

4 · Surface

The member sees it

With the reviewer's name attached: "✓ Reviewed by Dr. Reyes." Trust, visible.

🔒 The one hard rule of the prototype phase: fictional data only — no exceptions, not even "just one real patient" at a demo. HIPAA applies to real patient data, and our prototype environment can't legally hold it. The first real patient record — not scale, not maturity — is the trigger that moves us to compliant hosting. Until then we build every safeguard as if it were live, at near-zero extra cost.

HIPAA in three layers — what we build vs. what we buy

Layer 1 · Technicalwe build

Safeguards in the code

Role-based access per audience; the employer wall; an audit log of every health-data read; encryption in transit and at rest; consent captured before the first conversation; session timeouts. Built from Milestone 0 — nearly free now, brutally expensive to retrofit.

Layer 2 · Infrastructurewe buy

Compliant vendors, under BAAs

Every vendor touching real patient data signs a business-associate agreement: host, database, error tracking, email, and the AI provider (open decisions #4–5). One sneaky rule already adopted: push notifications never contain health details — Apple and Google won't sign BAAs.

Layer 3 · Administrativemostly buy

Policies, training, audits

Privacy officer, staff training, risk assessments, breach procedures. Compliance-automation platforms (Vanta, Drata) turn months of consulting into a subscription. Switched on in the weeks before the first real patient — the legal duty stays ours; the paperwork mostly doesn't.

07 · Design backlog

What the prototype doesn't cover

The v2.1 prototype fully specifies the patient app's happy path — nine screens, and we're following them faithfully, including the 3.0 refinement register. Everything here has to be invented: it needs design attention before its milestone arrives. This list is the design team's queue.

Patient app

Gaps around the edges of a well-specified core

  • Sign-in & account creation (the splash's "Already a member?" leads nowhere yet)
  • Employer eligibility check — invite code or work-email verification
  • Consent & privacy screens — legally required before the first conversation, and they sit right on top of the "no forms" promise; needs the most careful design on this list
  • Booking edges: reschedule, cancel, reminders (and payment, pending decision #1)
  • The practice player — media, timer, completion
  • Chat history & the real voice experience (decision #2)
  • Day-one empty state — what does Insight home show before any data exists?
  • Loading, error, offline states · rewards unlocked state · settings · data export & deletion

Practitioner app entirely undesigned

Half the product; zero screens exist

  • The insight review queue — needed for Milestone 2; the next thing to design
  • Visit-brief review & editing
  • Prescribing practices to a member
  • Availability management
  • Patient roster & messaging
  • Design-partner practitioners (decision #3) should shape all of this

Employer portal entirely undesigned

Last milestone; design can wait, but not forever

  • Aggregate engagement dashboards
  • Outcome reporting — what employers actually get for their money
  • Org & seat management
  • Every view designed within the no-individual-data wall

08 · Glossary

The acronyms, in plain terms

PHI
Protected Health Information — any health data tied to an identifiable person. The thing HIPAA protects, the thing employers never see, the thing our prototype servers never hold.
HIPAA
The US law governing how PHI must be protected — technical safeguards, vendor contracts, and organizational duties. Applies to real patient data, not our fictional development data.
EHR
Electronic Health Record — the practitioner's system of record for patients, charts, and appointments. Practitioners keep theirs; we connect to it.
FHIR
Pronounced "fire" — the healthcare industry's standard format for exchanging health data between systems. Our sandbox speaks it so real EHR integrations become a swap, not a rebuild.
BAA
Business Associate Agreement — the HIPAA-required contract with any vendor that touches PHI on our behalf. The gating factor in open decisions #4 and #5.
API
The doorway through which apps talk to the platform. Ours has three — one per audience, each with its own rules.
Sandbox EHR
Our miniature fake practice-records system, filled with fictional patients, used for development until a real EHR integration exists.
Expo / EAS
The toolkit we use to build the mobile app once and ship it to both iPhone and Android; EAS is its cloud build service (builds happen in the cloud — no one needs Xcode installed).
Monorepo
One repository holding all the codebases side by side, so a change spanning backend and apps is a single reviewed change.
Review gate
Our rule that no AI-drafted content reaches a patient until a clinician approves it — enforced by the data model, visible to members as "✓ Reviewed by Dr. Reyes."
M0–M4
The five build milestones: scaffold, patient spine, insight loop, care surface, employer portal & rewards.
LLM
Large Language Model — the class of AI (Claude, in our case) that reads conversations, extracts health facts, and drafts insights for clinician review.