Quick Start

Run Cloud Health Office locally and take a claim all the way through adjudication, payment, and 835 ERA download — no Azure account needed. Total time: under 15 minutes.

What you'll build

By the end of this guide you'll have a running local stack with MongoDB, Redis, and three core services — and you'll have submitted a claim through NCCI edit checking, fee schedule lookup, benefit calculation, cost-sharing, payment batching, and 835 ERA generation.

Prerequisites

Tool	Version	Notes
`Docker Desktop`	4.x+	Must have Docker Compose v2
`Node.js`	18+	For CLI tooling
`curl`	any	For API calls
`jq`	any	Optional — for pretty JSON output

1. Clone & Install

Clone the repository and install dependencies

# Clone
git clone https://github.com/aurelianware/cloudhealthoffice.git
cd cloudhealthoffice

# Install Node.js dependencies (for CLI tooling)
npm install

2. Start the Stack

Launch all services with Docker Compose

docker compose up -d

This starts MongoDB (localhost:27017), Redis (localhost:6379), and three core services:

Service	URL
claims-service	`http://localhost:5001`
benefit-plan-service	`http://localhost:5002`
payment-service	`http://localhost:5003`

Wait about 45 seconds, then verify all services are healthy:

curl -s http://localhost:5001/health
curl -s http://localhost:5002/health
curl -s http://localhost:5003/health

All should return Healthy.

3. Seed Reference Data

Set tenant ID and seed NCCI/MUE edits

All requests require an X-Tenant-ID header. For local development, use any string:

TENANT="demo"

# Seed NCCI Q1 2025 baseline edits
curl -s -X POST http://localhost:5002/api/v1/ncci/seed \
  -H "X-Tenant-ID: $TENANT" | jq .

The response includes an editCount showing the number of NCCI pairs loaded.

4. Create a Benefit Plan & Submit a Claim

Create a PPO plan with cost-sharing rules

PLAN=$(curl -s -X POST http://localhost:5002/api/benefitplans \
  -H "X-Tenant-ID: $TENANT" \
  -H "Content-Type: application/json" \
  -d '{
    "planId": "LOCAL-PPO-2025",
    "planName": "Local Dev PPO 2025",
    "payer": "Demo Health",
    "effectiveDate": "2025-01-01T00:00:00Z",
    "planType": "PPO",
    "lineOfBusiness": "Commercial",
    "costSharing": {
      "individualDeductible": 1500.00,
      "familyDeductible": 3000.00,
      "individualOutOfPocketMax": 5000.00,
      "familyOutOfPocketMax": 10000.00
    },
    "benefits": [
      {
        "serviceCategory": "98",
        "description": "Professional Office Visit",
        "inNetworkCopay": 30.00,
        "deductibleApplies": false
      },
      {
        "serviceCategory": "73",
        "description": "Diagnostic Lab",
        "inNetworkCoinsurance": 0.20,
        "deductibleApplies": true
      }
    ]
  }')

PLAN_ID=$(echo $PLAN | jq -r '.id')
echo "Plan ID: $PLAN_ID"

Submit an 837P-equivalent claim

An office visit (CPT 99213) at POS 11 with a billed amount of $175:

CLAIM=$(curl -s -X POST http://localhost:5001/api/claims \
  -H "X-Tenant-ID: $TENANT" \
  -H "Content-Type: application/json" \
  -d '{
    "claimNumber": "LOCAL-TEST-001",
    "memberId": "MBR001",
    "subscriberId": "SUB001",
    "providerNpi": "1234567890",
    "serviceDate": "2025-06-15T00:00:00Z",
    "diagnosisCodes": ["Z00.00"],
    "serviceLines": [{
      "procedureCode": "99213",
      "placeOfServiceCode": "11",
      "billedAmount": 175.00,
      "units": 1,
      "diagnosisCodes": ["Z00.00"]
    }],
    "totalBilledAmount": 175.00,
    "status": "Submitted"
  }')

CLAIM_ID=$(echo $CLAIM | jq -r '.id')
echo "Claim ID: $CLAIM_ID"

5. Adjudicate the Claim

Run the full adjudication pipeline

This calls the combined endpoint which runs NCCI/MUE edit check, fee schedule lookup, and benefit calculation in a single pass:

ADJ=$(curl -s -X POST http://localhost:5002/api/v1/adjudication/adjudicate \
  -H "X-Tenant-ID: $TENANT" \
  -H "Content-Type: application/json" \
  -d "{
    \"claimId\": \"$CLAIM_ID\",
    \"memberId\": \"MBR001\",
    \"planId\": \"LOCAL-PPO-2025\"
  }")

echo $ADJ | jq .

What happens during adjudication

NCCI check: CPT 99213 has no NCCI conflicts — passes. Fee schedule: No local schedule seeded, falls back to billed charges ($175). Benefit calculation: POS 11 resolves to service type "98" (Professional Visit); $30 copay applies, deductible not consumed. Result: Allowed $175, plan pays $145, member owes $30 copay.

6. Generate Payment & 835 ERA

Create a payment batch and download the X12 835

# Create payment batch
BATCH=$(curl -s -X POST http://localhost:5003/api/v1/payment/batch \
  -H "X-Tenant-ID: $TENANT" \
  -H "Content-Type: application/json" \
  -d '{ "batchDate": "2025-06-20T00:00:00Z" }')

BATCH_ID=$(echo $BATCH | jq -r '.batchId')

# Download the 835 ERA file
curl -s "http://localhost:5003/api/v1/payment/era/$BATCH_ID" \
  -H "X-Tenant-ID: $TENANT" -o era-835.edi

cat era-835.edi

The output is a valid X12 835 Electronic Remittance Advice file showing the claim payment details.

7. Verify FHIR R4 APIs

Test the CMS-0057-F FHIR endpoints

# FHIR CapabilityStatement
curl -s http://localhost:3000/fhir/r4/metadata | jq .resourceType

# Patient Access API — retrieve claims as FHIR resources
curl -s -H "Authorization: Bearer test-token" \
  "http://localhost:3000/fhir/r4/Claim?patient=MBR001" | jq .

# Explanation of Benefits
curl -s -H "Authorization: Bearer test-token" \
  "http://localhost:3000/fhir/r4/ExplanationOfBenefit?patient=MBR001" | jq .

You're done!

You've just run a claim through the complete Cloud Health Office pipeline — NCCI edit checking, benefit calculation, cost-sharing, payment, 835 ERA generation, and FHIR R4 API verification. All locally, with synthetic data, in under 15 minutes.

Next Steps

Now that you have a running local stack, explore these areas: