Integration Service

Central API gateway connecting Canvas Medical, Stripe, pharmacies, and all frontend applications.

Overview

The Integration Service is the central API gateway for the YourEra platform. It is a Next.js application running on ECS Fargate that serves as the Backend for Frontend (BFF) for both the Admin Portal and Patient Portal, while also coordinating all external service integrations.

Rather than a pure microservices architecture, the Integration Service acts as a "slimmed monolith" that provides a single coordination point for Canvas Medical, Stripe, PioneerRx, Boothwyn, FedEx, HubSpot, Zoom, and other external services.

Infrastructure

Service Integrations

┌─────────────────────────────────────────────┐
│           Integration Service (ECS)          │
├──────────┬──────────┬──────────┬─────────────┤
│  Canvas  │  Stripe  │ Pharmacy │  External   │
│  FHIR    │ Payment  │  Router  │  Services   │
│  API     │  API     │          │             │
├──────────┼──────────┼──────────┼─────────────┤
│ Patient  │ Setup    │ Pioneer  │ FedEx       │
│ Task     │ Intent   │ Rx       │ HubSpot     │
│ MedReq   │ Payment  │ Boothwyn │ Zoom        │
│ Comms    │ Intent   │ Strive   │ SendGrid    │
│ Schedule │ Refund   │          │ Twilio      │
└──────────┴──────────┴──────────┴─────────────┘

Authentication

The Integration Service uses three authentication mechanisms depending on the caller:

1. ADMIN_SECRET (Server-to-Server)

Internal services (e.g., Canvas plugins, cron jobs) authenticate by including the ADMIN_SECRET value in the Authorization header. This bypasses JWT validation and grants full admin access.

Authorization: Bearer <ADMIN_SECRET>

2. Admin JWT (Portal Users)

Admin Portal users authenticate via OTP, Canvas HMAC, or Magic Link to receive a JWT with 24-hour expiry. The requireAdmin() middleware validates the JWT on all /api/admin/*, /api/tasks, /api/task-action, and /api/rx-queue/* endpoints.

3. HMAC (Canvas Plugin)

The Canvas prescription_queue plugin signs requests with a shared secret (CANVAS_AUTH_SECRET, same value as ADMIN_JWT_SECRET). The signature includes a timestamp for replay protection.

Admin API

The Admin API serves the Admin Portal with endpoints for dashboard statistics, patient management, order tracking, and operational tools. All endpoints require admin authentication.

Endpoints

RxQueue API

The RxQueue API powers the prescription approval workflow in the Admin Portal. Tasks originate as Canvas FHIR tasks and are enriched with patient data before being presented to the practitioner.

Patient API

The Patient API provides endpoints consumed by the Patient Portal. These endpoints are also available to internal services via the ADMIN_SECRET header.

Canvas Integration

The Integration Service is the primary consumer of the Canvas Medical FHIR API. It uses OAuth2 client credentials for authentication and interacts with Canvas for patient management, clinical data, task workflow, and messaging.

OAuth2 Authentication

// Token request (client credentials grant)
POST https://yourera.canvasmedical.com/auth/token/
grant_type=client_credentials
client_id=<CANVAS_CLIENT_ID>
client_secret=<CANVAS_CLIENT_SECRET>

FHIR Resources Used

Payment System

The Integration Service manages the full Stripe payment lifecycle. Cards are saved during intake and charged later when a prescription is approved.

Payment Flow

1. Intake: A SetupIntent is created to securely save the patient's card
2. Card Saved: The PaymentMethod ID is stored in the payment_holds table
3. Approval: When the orchestrator approves a prescription, it calls chargePaymentHold(canvasPatientId)
4. Charge: An off-session PaymentIntent is created using the saved PaymentMethod
5. Refill: Subsequent charges use the same saved PaymentMethod

Discount Codes

Patient Records

The Integration Service maintains immutable intake snapshots in the database. These serve as a redundancy layer — if Canvas data is ever unavailable, the original intake submission is preserved for recovery.

Storage Model

• Immutable: Once an intake is submitted, the record is never modified
• Complete: Contains the full questionnaire response, demographics, and metadata
• Indexed: Searchable by Canvas patient ID, email, and submission date
• Encrypted: Stored with AES-256-GCM encryption via encryptAndStore/retrieveAndDecrypt

Pharmacy Routing

The Integration Service contains the state-based pharmacy routing logic that determines which compounding pharmacy fulfills each prescription and which prescriber is assigned.

State Routing Rules

Prescriber Assignment

The getPrescriberForState() function in medication-config.ts routes to the correct prescriber based on the patient's state:

Scheduling

The Integration Service provides the scheduling engine for telehealth appointments. It combines Canvas practitioner schedules with Zoom meeting creation to provide end-to-end appointment management.

Components

• Availability Engine: Queries Canvas FHIR Schedule/Slot resources to determine open time slots
• Zoom Integration: Creates Zoom meetings automatically when appointments are booked
• Appointment Storage: Appointments are stored in both Canvas (as Appointments) and the integration DB (for portal queries)
• Notifications: Confirmation emails and 24-hour reminders sent via the Notification Service

Zoom Meeting Creation

// Zoom meeting is created with patient and practitioner details
{
  "topic": "YourEra Telehealth - Dr. Singh",
  "type": 2,  // Scheduled meeting
  "start_time": "2026-03-23T14:00:00Z",
  "duration": 15,
  "settings": {
    "join_before_host": true,
    "waiting_room": true
  }
}