Junction Integration

Junction appears in this repository as an integration boundary rather than a full checked-in adapter. That distinction matters when you write platform docs or wire workflows that depend on external clinical data.

What exists in this repo

The repository currently includes:

• validated Junction environment variables in apps/my-loop-health/src/lib/env.ts
• example environment keys in apps/my-loop-health/.env.example
• deployment and ops guidance in ops/DEPLOYMENT_GUIDE.md

JUNCTION_HEALTH_API_KEY=replace-me
JUNCTION_HEALTH_CLIENT_ID=replace-me
JUNCTION_HEALTH_CLIENT_SECRET=replace-me

What is not checked in here

This tree does not expose a concrete Junction client package or a complete app-local adapter comparable to:

• @loop/patient-graph-client
• Luna’s tool registry
• the workflow engine

That means your docs and implementations should treat Junction as:

1. a deployment-specific contract
2. an external data source
3. a boundary that may differ across environments

Where Junction fits conceptually

When present, Junction would typically contribute external clinical inputs into the platform:

Junction credentials
      |
      v
External clinical data fetch
      |
      v
Normalization into platform context
      |
      v
Workflow execution or patient graph write

Safe documentation pattern

Use this shape when documenting Junction-dependent logic:

type JunctionConfig = {
  apiKey: string;
  clientId: string;
  clientSecret: string;
};
 
function hasJunctionConfig(env: NodeJS.ProcessEnv): boolean {
  return Boolean(
    env.JUNCTION_HEALTH_API_KEY &&
    env.JUNCTION_HEALTH_CLIENT_ID &&
    env.JUNCTION_HEALTH_CLIENT_SECRET,
  );
}

This pattern keeps the platform code explicit about the dependency without pretending a specific adapter exists in the current branch.

Recommended integration approach

If you need Junction-backed data in a workflow:

1. fetch Junction data in an integration layer
2. normalize it into context.data
3. run the workflow against normalized fields
4. write durable records to the Patient Graph when appropriate

const context = {
  patientId: 'user_123',
  data: {
    biomarker: {
      TSH: 4.2,
    },
    source: 'junction',
  },
};
 
const result = await workflow.execute(context);

Example normalization contract

Keep external vendor fields out of workflow conditions where possible.

Prefer:

const normalized = {
  biomarker: {
    TSH: 4.2,
    A1C: 5.8,
  },
  medications: ['metformin'],
  sourceSystem: 'junction',
};

Over:

const vendorShapedContext = {
  junctionPayload: {
    lab_panel: {
      tsh_value: 4.2,
    },
  },
};

The normalized form is easier to test and easier to keep stable across integration vendors.

Operational considerations

If you add a Junction adapter later, document:

• credential ownership
• refresh and token handling
• retry behavior
• failure modes
• mapping into Patient Graph or workflow context

Current recommendation

For this repository snapshot:

• document Junction as an external integration seam
• keep examples high-level and normalized
• avoid claiming a fully implemented adapter unless the code lands in the tree

Next steps

• See Patient Graph Integration
• Review 4D Chess Architecture
• Continue to Genetics Inputs