Architecture Overview

Canvas-first microservice architecture. Canvas FHIR is the medical-record database of record; every service we build is a single-purpose sidecar around it. One Canvas instance serves YourEra DTC and every GuideGLP B2B client via FHIR-native multi-tenancy.

The Principle

Canvas FHIR is the medical-record database. Every clinical fact lives in Canvas. Our services are sidecars around it.

For everything else — payments, shipping logistics, tenant branding, notification delivery, schedulers, compliance archives — we build lean single-purpose sidecar services that hold the minimum state needed to do their job and reference Canvas for clinical truth. One Canvas instance, many Organizations: YourEra DTC is a FHIR Organization; each GuideGLP client (Biologics, LCMC, Sleep Corner, etc.) is also a FHIR Organization. Every Patient has a managingOrganization pointing to one of them.

The decision rule when designing anything new:

Would a HIPAA auditor expect this data in an EMR? Then Canvas owns it.
Would a Stripe auditor, FedEx tracking system, or CMS-style operational dashboard expect this data? Then a sidecar owns it.

No caching Canvas data "just in case." No storing clinical fields in sidecars. No cross-database joins. Read canvas-first-principles for the full doctrine.

System Diagram

Canvas-first service mesh. Every service is a sidecar around Canvas FHIR. Portals (patient + admin) read/write Canvas directly via the @yourera/canvas-client shared library; sidecars either write Canvas at intake completion (intake-gateway), via the saga (prescription-orchestrator writing MedicationDispense + Task), or never (most). Arrows show the primary data flow; async event traffic flows through the central event bus (SQS + EventBridge) with outbox delivery guarantees.

For the architectural doctrine behind this diagram (why Canvas-first, what can and cannot live in a sidecar, what we explicitly reject) see canvas-first-principles.

Pipeline Walkthrough

The full patient journey from intake to delivered Rx under the Canvas-first architecture.

Service Catalog

Inter-Service Communication

Two communication styles, picked per use case:

1. Async events (primary). Outbox pattern from each producer; SQS/EventBridge delivers at-least-once. Consumers must be idempotent. Used for everything that doesn't need a synchronous response.
2. Direct HTTP (fallback). Service-to-service JWT signed with a shared secret per service pair. Used when the caller genuinely needs the response now (e.g., admin-portal calling commerce to create a refund).

Event Naming Convention

{domain}.{entity}.{past-tense}

Examples: intake.completed, patient.created, payment.intent_succeeded, rx.fill_completed, refill.due, pharmacy.dispense_confirmed, shipping.delivered.

Call Graph (HTTP, when sync is required)

Async Event Examples

Database Topology

Each service owns its own Postgres database. No cross-service DB access; services communicate only via APIs and events. No DB-level foreign keys cross service boundaries — UUIDs only, app-enforced.

Every service also has outbox and audit_events tables for event reliability and action audit, per the Canvas-first doctrine.

Multi-Tenancy

One Canvas instance serves every Organization — YourEra DTC and every GuideGLP client. FHIR-native multi-tenancy via Patient.managingOrganization. Tenant isolation is enforced in our service layer, not by Canvas. GuideGLP clients get perceived isolation — white-labeled portals, tenant-scoped admin views, their own branded notifications — but share infrastructure.

What Each GuideGLP Client Gets

• ✅ White-labeled patient portal at their domain (e.g., patients.sleepcorner.com).
• ✅ Admin portal that shows only their patients (tenant-scoped at every service query).
• ✅ Email/SMS from their verified sender addresses with their branding.
• ✅ Intake forms at their domain with their colors, logo, and support copy.
• ✅ Their providers see tasks routed to them through Canvas prescription_queue.

What We Do NOT Promise

• ❌ Data isolation inside Canvas — YourEra prescribers see every patient across every org.
• ❌ Dedicated infrastructure — one Canvas, one Postgres cluster, shared services.

Single-Org-For-Life

A patient belongs to exactly one organization for their entire lifetime with us. A person who is both a DTC customer and a Biologics employee does not get modeled as two records — they enter through one funnel. organization_id is set once at patient_directory creation and is immutable through normal flows. Superadmin corrective reassignment exists as a rare fix-it tool only.

Notification System

All outbound patient comms flow through the Notification Service. The service expanded significantly under Canvas-first: beyond the original delivery-only scope, it now owns a lightweight CRM layer (contacts + campaigns + preferences) that replaces HubSpot entirely.

Category Model (HIPAA-Aware)

Every notification falls into one of three categories. Opt-out rules are category-specific.

Campaign Types at v1

• Event-triggered drip — "on intake.abandoned, send day-1, wait 3 days, send day-4, wait 7 days, unenroll."
• Scheduled — cron-like, per-org timezone: "every Monday 9am send weekly_tip to active patients."
• One-off blast — admin composes, selects audience, sends.

Open/click tracking, A/B testing, inbound reply threading, and multi-language templates are explicitly deferred; schema is extensible.

Galleria Print Queue

Part of Shipping Service. When the orchestrator creates a Galleria (GMP) shipment, a print queue entry is auto-created; Galleria pharmacy staff see it in the Shipping Dashboard and print the label when packaging.

-- Print queue lifecycle
pending  →  printing  →  printed  →  (flows into pack/ship)
                       →  error    →  (retry)

Secure Intake Validation

Prevents client-side price tampering. The Intake Gateway issues an HMAC-signed plan token at plan selection; the signature is verified when the Stripe PaymentIntent is created. Coupled with Stripe Elements (card data never touches our server) and per-org verified senders, PCI + PHI scope stays tight.

// 1. Server generates plan token when client selects a plan
const payload = { planId, amountCents, intakeType, organizationId, ts: Date.now() };
const data = base64url(JSON.stringify(payload));
const sig  = HMAC-SHA256(data, PLAN_SIGNING_SECRET);
const planToken = data + '.' + sig;

// 2. Client sends planToken with Stripe PaymentIntent request

// 3. Server verifies on payment submission
const [data, sig] = planToken.split('.');
const expected = HMAC-SHA256(data, PLAN_SIGNING_SECRET);
if (sig !== expected) throw 'Tampered plan token';
if (payload.amountCents !== stripeAmount) throw 'Amount mismatch';
if (payload.organizationId !== resolvedOrg) throw 'Org mismatch';
if (Date.now() - payload.ts > 15 * 60 * 1000) throw 'Token expired';

Refactor Sequence

Under Canvas-first, services are built/retired in dependency order. Foundational services first, then the ones that depend on them. See canvas-first-principles §6 for the full rationale.

What Retires

Under Canvas-first, substantial prior-architecture artifacts go away entirely.

Testing Strategy

Each service is tested at four tiers:

• Unit tests — pure logic: state machines, preflight rules, preference checks, HMAC, template rendering, idempotency-key generation.
• Integration tests — with mocked HTTP dependencies (stub Stripe, Canvas, FedEx, pharmacy APIs). Assert state transitions + event emissions.
• Contract tests — every emitted/consumed event has a versioned schema; every inter-service API has a typed Zod contract. Cross-service consumers import from @yourera/contracts.
• E2E tests — browser-driven from intake through delivery for the happy path; targeted scenarios for blocked saga, payment failure, pharmacy rejection, custom-domain routing, tenant isolation.