Architecture Overview

Modular microservice architecture for the YourEra telemedicine platform. Each service is independently deployable, testable, and documented.

System Diagram

Eight services with clear boundaries. Arrows show HMAC-authenticated service-to-service calls.

Pipeline Walkthrough

The complete patient journey from intake to shipment, showing which service handles each step.

Service Catalog

Inter-Service Communication

All service-to-service calls use HMAC-SHA256 authentication (same pattern as Pharmacy Router and Physician Registry).

// Request headers
X-API-Key:    <identifies the caller>
X-Timestamp:  <ISO 8601, within 5 min>
X-Signature:  HMAC-SHA256("<timestamp>.<jsonBody>", apiSecret)

Call Graph

Database Topology

Each service owns its own database in the shared RDS instance. No cross-service DB access — services communicate only via APIs.

Multi-Physician Claim Model

Enables a pay-per-visit model where multiple physicians see the same patient. First to claim gets the case.

-- Atomic claim (exactly one winner in a race)
UPDATE prescription_assignments
SET status = 'claimed',
    claimed_by = $physicianId,
    claimed_at = NOW()
WHERE id = $assignmentId
  AND status = 'open';

Notification System

All notifications flow through the Notification Service. Templates and channel toggles are stored in the database and editable via the Admin Portal.

Channel Matrix

Each toggle is stored in notification_channel_config and editable via PUT /notify/channels/:type. The Admin Portal provides a UI with toggle switches.

Galleria Print Queue

Part of the Shipping Service. When the Orchestrator creates a GMP shipment, a print queue entry is auto-created. Galleria pharmacy staff see it in the Shipping Dashboard.

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

Secure Intake Validation

Prevents client-side price tampering. The Intake Gateway signs plan selections with HMAC, then verifies the signature matches the Stripe amount at payment time.

// 1. Server generates plan token when client selects a plan
const payload = { planId, amountCents, intakeType, 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

// 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 (Date.now() - payload.ts > 15 * 60 * 1000) throw 'Token expired';

Migration Phases

Services are extracted in dependency order — leaf services first, then services that depend on them.

ALB Routing

All services share a single domain (api.yourera.com) with path-based routing on the ALB.

Testing Strategy

Each service follows the established pattern (vitest, same as Pharmacy Router):

• Unit tests — Pure logic: routing, validation, HMAC, template rendering
• Service tests — Mocked HTTP dependencies (mock Physician Registry responses, etc.)
• Contract tests — Each service exports TypeScript interfaces for request/response shapes. Callers import and validate.