Organization Service

Tenant & admin directory. The table-of-organizations for both YourEra DTC and GuideGLP B2B clients. Owns per-org branding, portal config, notification config, custom domains, admin users, and physician × organization memberships.

Overview

The organization-service is the backbone of multi-tenancy. Every Canvas-first service that needs to know "which tenant is this?", "is this admin allowed to see this org?", or "which physician covers this patient?" calls organization-service first and Canvas second.

Canonical spec: /docs/schema/organization-domain.md in the platform monorepo. The source of truth for the table shapes, role matrix, and event taxonomy below.

Responsibilities

• Tenant directory. One row per Organization (YourEra DTC, Biologics, LCMC, Sleep Corner, etc.). Mirrored into Canvas FHIR as Organization resources; this service owns the non-FHIR attributes Canvas doesn't model.
• Branding, portal config, notification config. Per-org theme tokens, portal feature flags, and verified sender identity for email/SMS. Materialized for the patient portal and notification-service via event subscription.
• Custom domains. DNS verification lifecycle for white-label intake and portal hostnames (e.g. patients.sleepcorner.com).
• Admin users + memberships. Superadmin, org_admin, org_user, support. Admin users are created via Clerk then linked into org memberships.
• Physician memberships. Which physicians serve which orgs — used by the intake flow, the orchestrator, and the Canvas RxQueue plugin.

Non-responsibilities

• No clinical data. Patient records, MedicationRequests, Observations, Consents — all in Canvas.
• No Stripe. Org-level billing belongs in commerce-service / payment-service.
• No notification delivery. Only config. Sender identity moves; notification-service actually sends.
• No physician licensure. Owned by physician-registry; organization-service only holds the org↔physician relation.

Status

Database Schema

Ten tables owned by the service. All FKs are intra-service; nothing cross-service.

Auth & Role Matrix

All authenticated endpoints require a JWT issued by organization-service. The JWT is HS256, short-lived (15 min), and carries { sub, kind: 'admin', isSuperadmin, memberships: [{ orgId, role }] }. Admins obtain it via either a Clerk session exchange or an email-OTP verification (for admins without a Clerk identity yet).

HTTP Endpoints

Organizations

Per-org config

Custom domains

Admin users + memberships

Physician memberships

Custom Domain Lifecycle

White-label hostnames (portal and intake) flow through an explicit state machine:

Public Host Resolver

{
  "organization": {
    "id": "01HXY...",
    "slug": "sleepcorner",
    "kind": "b2b",
    "displayName": "Sleep Corner",
    "status": "active"
  },
  "branding": {
    "primaryColor": "#0b3a5b",
    "logoUrl": "https://cdn.../sleepcorner/logo.svg"
  },
  "portalConfig": {
    "messagingEnabled": true,
    "selfSchedulingEnabled": false
  }
}

Emitted Events

Every state change writes to outbox and is shipped to EventBridge by the outbox worker. All events carry organizationId so downstream subscribers can filter.

Outbox + Worker

Every write that would emit an event does so inside the same Postgres transaction via the outbox table. A background worker ticks every few seconds, pulls unshipped rows, posts them to EventBridge, and marks them shipped. Exactly-once is guaranteed by a unique outbox.id used as EventBridge idempotency_token; consumers are still expected to be idempotent.

Consumers

Who calls organization-service and why:

• Intake Gateway. Calls /public/resolve at session start to attach organization_id to the intake_sessions row.
• Patient Portal. Calls /public/resolve at edge to render branding and flip portal feature flags. Calls admin endpoints never.
• Admin Portal. Primary client. Uses the full admin API for org CRUD, membership management, and config editing.
• Notification Service. Subscribes to organization.* events to keep sender identity and branding in sync.
• Patient Service. Reads org metadata for the email-lookup privacy check and to verify callers have membership on body.organizationId.
• Physician Registry. Reads physician_org_memberships when computing routing eligibility.
• Webhook Receiver. Resolves Canvas resource → managingOrganization → internal org id on incoming Canvas webhooks.

Testing

510 unit tests live in services/organization-service/src/**/*.test.ts. Coverage split: role matrix exhaustively tested (every role × endpoint combination), custom-domain state machine property-tested, outbox emission verified for every mutating endpoint. Integration tests (real Postgres) are skipped in CI and run locally via pnpm test:integration --filter organization-service.

TODOs & Future Waves

• B2B contract table. Today, contract terms (pricing, prepaid bundles, margins) live in the commerce-service spec. They may migrate to organization-service or stay separate — pending the commerce-service design doc.
• Membership expiry. Currently memberships are permanent until revoked. Time-bound grants (e.g. locum physicians) are deferred.
• Audit export. audit_events is queryable via admin API but there's no bulk export for SOC2 review cycles. Planned.
• Per-domain cert rotation alerts. Cert expiry monitoring exists in infra, but a first-class alert at the org level (so org_admins can see domain health) is pending.
• Soft-delete for admin users. Currently only suspend. A terminal archived state for admin_users parallel to organizations is a Wave B follow-up.