YourEra Engineering Docs

How a prescription flows

1. Intake. Patient reaches their org's intake host (e.g., intake.biologics.com). intake-gateway resolves the organization from the hostname via organization-service, creates an intake_sessions row, and captures the email as a lead via contact.captured (consumed by notification-service).
2. Atomic Canvas write. On final submit, intake-gateway atomically writes Canvas resources via @yourera/canvas-client: Patient (with managingOrganization), Observation, Condition, AllergyIntolerance, QuestionnaireResponse, Consent, DocumentReference. In the same transaction, patient-service writes the patient_directory row + INSERT-only intake_snapshots.
3. Provider review in Canvas. A Canvas Task is routed to eligible physicians (via physician-registry + the Canvas prescription_queue plugin, now org-aware). Provider reviews, approves, signs the Rx. Canvas emits MedicationRequest.status = active.
4. Orchestrator saga. webhook-receiver ingests the Canvas webhook and emits canvas.medication_request.activated. prescription-orchestrator creates an rx_fill_sagas row and runs the state machine: preflight → payment (or skipped if prepaid plan) → pharmacy → shipping → notify.
5. Pharmacy routing (live per fill). Orchestrator asks pharmacy-router for a route: Galleria (GMP) if licensed in the patient's state, else Strive. Routing is re-evaluated on every fill — a patient who went to Strive for fill #1 automatically routes to GMP for fill #2 if GMP adds a license in between. Pharmacy dispenses; router writes Canvas MedicationDispense on callback.
6. Fulfillment + notification. shipping-service generates a FedEx 2Day Express label (fetching patient address live from Canvas, never cached). notification-service sends templated patient updates (shipped → out-for-delivery → delivered) using the org's verified sender identity.
7. Refill cycle. refill-scheduler maintains a materialized view of upcoming refills fed by Canvas webhooks. On due date, it fires refill.due; orchestrator creates a new saga and runs the full pipeline again. Prepaid bundled plans (quarterly, 6-month) skip the charge stage — money was collected upfront.

Mental model: Canvas owns clinical truth; sidecars hold operational state

The one thing to internalize: Canvas FHIR is the medical-record database. Every clinical fact — demographics, vitals, conditions, allergies, prescriptions, dispenses, messages — lives in Canvas. Our services are sidecars that hold only what Canvas doesn't model.

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.

Concrete consequences:

• No caching Canvas data "just in case." If a read is hot, build a materialized view fed by webhooks (like refill-scheduler). Not an ad-hoc cache.
• No clinical fields in sidecars. Shipping-service doesn't store patient names. Notification-service doesn't store Rx details. Everything references canvas_patient_id and fetches live.
• Cross-service joins are forbidden. Every service has its own Postgres. Foreign keys don't cross service boundaries.
• Bypassing the owner is forbidden. Need patient data? Call patient-service, which calls Canvas. The only service that can talk Canvas directly is the one whose domain it is.
• No platform = 'yourera' | 'guideglp' discriminator. Tenants are FHIR Organizations. Organization.kind distinguishes DTC from B2B where branching is needed.

Gotchas before you touch anything

Environments & addresses

Where to go next

Depending on what you're working on:

Full service index