Currently Healthcare Data Platform — Product Requirements Document

---

PRD Metadata

---

v0.1 Spark — Problem & Outcomes

Problem Statement

Health Information Exchanges (HIEs) and the hospitals that connect to them generate clinical documents in legacy formats — HL7 v2 messages and CDA/CCDA XML — that are structurally inconsistent, heavily encoded in proprietary local terminologies, and incompatible with modern analytics platforms. Translating this data into FHIR R4 or OMOP CDM 5.4 today requires bespoke engineering work at every site, consuming months of integration effort, introducing mapping errors, and producing datasets that cannot be federated across organizations.

No turnkey commercial product resolves all three layers of this problem simultaneously: (1) format normalization from HL7/CDA to FHIR bundles, (2) terminology resolution against standardized vocabularies (LOINC, SNOMED CT, ICD-10-CM, RxNorm), and (3) phenotype-ready OMOP CDM output for real-world evidence and population health use cases.

Desired Outcomes

Constraints

• HIPAA PHI Isolation: All protected health information is stored exclusively in the PHI Cloud SQL instance. The Platform Cloud SQL instance (orchestrator, 192.168.0.251) contains zero PHI. This boundary is enforced at the schema level and is non-negotiable.
• Authentication: All user sessions are managed through Clerk. The /api/web/auth/sync-user route synchronizes Clerk identity to the platform database. Custom auth implementations are out of scope.
• Deployment Flexibility: Pipeline workers must support both GKE-managed deployment and on-premise installation for HIEs with air-gapped or data-residency requirements. Four Dockerfiles (Dockerfile, Dockerfile.nlp, Dockerfile.pipeline, Dockerfile.worker) define the container boundary.
• HL7 Profile Coverage: Message type support is bounded by the profiles defined under config/hl7_profiles/ — currently ADT A01/A02/A03/A04/A08/A13/A28/A31, DFT P03, MDM T02, ORM O01, ORU R01/R32, RDE O11, SIU S12, VXU V04.
• Vocabulary Source: Terminology resolution uses OMOP Athena vocabulary loaded into omop_cdm54.concept. Updating this vocabulary outside of a scheduled Athena release is out of scope.

---

v0.2 Market Definition — ICP & Segments

Ideal Customer Profile

The primary buyer is a Health Information Exchange operating in the United States that needs to deliver standardized clinical data to member hospitals, research sponsors, or payer networks. The secondary buyer is a mid-to-large hospital or health system that connects to one or more HIEs and wants self-service access to their own FHIR and OMOP data without depending on the HIE's timeline.

Segments Table

"Not For"

Currently is not designed for:

• Direct EHR vendors seeking a full-featured EHR replacement or clinical workflow system. Currently produces structured data outputs; it does not manage clinical workflows, orders, or clinical decision support.
• Single-physician practices with fewer than a few hundred records per month. The infrastructure cost and onboarding complexity are not justified at that scale.
• International deployments requiring non-US vocabularies as the primary code system. The Athena vocabulary is US-centric (ICD-10-CM, RxNorm, CPT). International vocabulary support is not in the current roadmap.
• Real-time point-of-care alerting systems requiring sub-second latency. The Celery-based asynchronous pipeline is optimized for throughput, not real-time clinical decision latency.

---

v0.3 Commercial Model — Pricing & Positioning

Positioning Statement

Currently is the first platform built specifically for HIEs to transform legacy clinical document formats into analytics-ready FHIR R4 and OMOP CDM 5.4 at network scale — with built-in terminology resolution, PHI-safe architecture, and self-service portals for every stakeholder in the care continuum.

Monetization Model

Currently operates a B2B SaaS subscription model. The API surface confirms two commercial primitives:

1. Organization Subscriptions — HIE network operators and facility organizations subscribe to the platform. Subscription management is handled via:

   • POST /api/web/subscriptions/checkout — initiates checkout for a new subscription tier
   • POST /api/web/subscriptions/cancel — cancels an active subscription
   • GET /api/web/admin/pricing/tiers — returns available pricing tiers for display and selection

2. Usage-Based API Access — API keys are provisioned per organization and tracked for consumption. Platform-level API key metrics are available at GET /api/web/v1/admin/api-keys/metrics/platform. Individual organization API key management is exposed via GET /api/web/v1/admin/api-keys and the CLI (cli/src/commands/keys.ts, cli/src/commands/billing.ts).

Revenue analytics are surfaced to platform administrators via GET /api/web/admin/revenue/stats and per-organization breakdowns at GET /api/web/v1/admin/analytics/by-org.

Pricing Tiers (Inferred from API surface)

Moat Thesis

Currently's durable competitive advantage rests on three compounding assets:

1. Vocabulary Coverage: The OMOP Athena vocabulary (6.3M concepts) loaded into omop_cdm54.concept is operationally expensive to license, load, and keep current. Competitors must replicate this to match terminology resolution quality.
2. HL7 Profile Depth: The config/hl7_profiles/ directory contains 18 message-type-specific conformance profiles alongside field definitions and HL7 table lookups across 80+ table IDs. This institutional knowledge of real-world HL7 variance cannot be replicated without extensive production data exposure.
3. PHI Architecture Pattern: The strict two-database architecture (Platform Cloud SQL + PHI Cloud SQL) with Clerk-managed RBAC creates a compliance posture that is difficult and expensive for new entrants to replicate. Existing customers have already validated their security assessments against this architecture.

---

v0.4 User Journeys

UJ-001: HIE Onboarding and Network Activation

Actor: HIE Network Administrator
Entry Point: Platform landing page → registration flow

1. HIE administrator submits registration via POST /api/web/registrations/hie.
2. Platform admin reviews and approves the registration at /admin using GET /api/web/admin/registrations/hie and approving via GET /api/web/admin/registrations/hie/:id.
3. Clerk organization is created; webhook triggers sync to organizations table.
4. HIE administrator completes onboarding (onboarding_completed = TRUE on the organizations record).
5. HIE administrator accesses the /dashboard/network shell and invites member facility users via POST /api/web/admin/invitations/facility-user.
6. HIE administrator configures API keys at /dashboard/network/settings/api-keys.

Success Condition: HIE organization is active, at least one member facility is linked, and the HIE can view the network overview at /dashboard/network/page.tsx.

---

UJ-002: Facility File Upload and Pipeline Processing

Actor: Hospital Data Coordinator
Entry Point: /dashboard → Upload

1. Facility user authenticates via Clerk; session is synced via POST /api/web/auth/sync-user.
2. User navigates to the upload interface (/dashboard/network/upload/page.tsx) and selects HL7 or CDA files. Allowed file types are configurable per hospital (allowed_file_types on the hospitals table; defaults to ['hl7', 'cda', 'fhir']).
3. Files are submitted to POST /api/web/files. The platform registers file metadata in file_registry (file name, type, SHA-256 hash for deduplication, size) and enqueues a pipeline task.
4. FastAPI + Celery workers pick up the task and execute the Parse → Clean → FHIR → OMOP pipeline stages.
5. Job status is visible in real time at /dashboard/network/jobs/page.tsx.
6. On completion, FHIR R4 bundles are stored in PHI Cloud SQL and OMOP CDM 5.4 records are written to omop_cdm54 schema.

Success Condition: file_registry.status transitions from pending → processing → completed; FHIR and OMOP records are queryable.

---

UJ-003: Clinical Data Exploration and Export

Actor: Health Data Analyst at an HIE or research institution
Entry Point: /dashboard/network/records or API

1. Analyst authenticates and navigates to /dashboard/network/records/page.tsx to browse processed medical records.
2. Analyst views patient-level records (de-identified MRN hash) at /dashboard/network/patients/[mrnHash]/page.tsx.
3. Analyst configures OMOP CDM export at /dashboard/network/export/page.tsx.
4. For programmatic access, analyst retrieves an API key from /dashboard/network/settings/api-keys or via currently keys CLI command.
5. CLI commands provide structured access: currently records, currently diagnoses, currently medications, currently allergies, currently encounters.

Success Condition: Analyst can export a complete OMOP CSV round-trip (validated by tests/e2e/test_omop_csv_round_trip.py) and query records programmatically via API key.

---

UJ-004: Patient Portal Access and Record Sharing

Actor: Patient
Entry Point: Email invitation

1. Platform or facility admin sends a patient invitation via POST /api/web/admin/invitations/patient.
2. Patient receives email, follows invitation token link to GET /api/web/invitations/:token.
3. Patient completes onboarding via POST /api/web/onboarding/patient.
4. Patient accesses the /portal shell and views their longitudinal health records at /portal/records/page.tsx.
5. Patient manages data sharing permissions at /portal/sharing/page.tsx.
6. Patient can generate personal API access tokens at /portal/settings/api-access/page.tsx using the patient-api-access-client.tsx component.

Success Condition: Patient can view all processed records associated with their identity and control sharing with third parties.

---

UJ-005: Platform Administrator Operations

Actor: Currently Platform Administrator
Entry Point: /admin

1. Admin monitors platform analytics at /admin/analytics/page.tsx.
2. Admin reviews and approves pending HIE and facility registrations via GET /api/web/admin/registrations/hie and GET /api/web/admin/registrations/facility.
3. Admin approves provider credentials via POST /api/web/v1/admin/approve-provider.
4. Admin reviews PHI access audit logs at GET /api/web/v1/admin/audit/phi-access.
5. Admin manages org-to-org link approvals at POST /api/web/admin/org-links/approve.
6. Admin manages facility organization creation at POST /api/web/admin/facility-orgs/create.
7. Admin reviews revenue statistics at GET /api/web/admin/revenue/stats.

Success Condition: Admin can execute the full approval lifecycle for a new HIE or facility within the /admin shell without direct database access.

---

v0.5 Red Team Review

Risk Register

---

v0.6 Architecture

TECH-001: Four-Tier Application Architecture

Currently decomposes into four runtime tiers:

1. Web Application (TECH-001a): Next.js deployed on Vercel. Four route-group shells handle distinct user roles: (platform)/admin, (hie)/dashboard/network, provider /dashboard, and (patient)/portal. Drizzle ORM connects to Platform Cloud SQL.
2. Processing Pipeline (TECH-001b): FastAPI (Python 3.11) serving the pipeline API, containerized via Dockerfile.pipeline. Exposes a REST interface consumed by the web app for task enqueueing (per commit 2ee79b5).
3. Celery Workers (TECH-001c): Async task workers containerized via Dockerfile.worker, using Redis as the message broker. Execute the Parse → Clean → FHIR → OMOP stage sequence for each uploaded file.
4. NLP Service (TECH-001d): Separate container (Dockerfile.nlp) indicating a natural language processing component, likely for clinical text extraction from unstructured CDA sections.

TECH-002: Data Architecture

TECH-003: Authentication and Authorization

Clerk manages the identity plane. Organizations, user memberships, and roles are created in Clerk and synchronized to Platform Cloud SQL via webhook. The users table stores clerk_id, clerk_role, and organization_id. Session validation occurs at GET /api/web/session. NPI verification is performed at POST /api/web/npi/verify as part of facility onboarding.

TECH-004: CLI (cli/)

A TypeScript CLI (cli/bin/currently.ts, distributed as cli/dist/bin/currently.js) provides programmatic access for analysts and integrators. Commands cover the full API surface: auth, billing, config, keys, orgs, patient, pipeline, records, diagnoses, medications, allergies, encounters, analytics, quality, storage, webhooks. Authentication uses a token store at cli/src/auth/store.ts resolved via cli/src/auth/resolve.ts.

API-001: Platform Administration APIs

API-002: HIE and Facility APIs

API-003: Auth, Session, and Subscription APIs

DBT-001: OMOP CDM 5.4 Schema

The PHI Cloud SQL instance hosts the full OMOP CDM 5.4 schema under the omop_cdm54 schema prefix. Key tables populated by the pipeline include:

TECH-005: CI/CD Pipeline

Seven GitHub Actions workflows govern the delivery pipeline:

TECH-006: HL7 Profile Configuration

Eighteen message-type conformance profiles under config/hl7_profiles/ drive the parsing and validation layer. Field definitions are centralized in config/hl7_profiles/field_definitions.json. HL7 table lookups are distributed across 80+ files in config/hl7_tables/ (table IDs 0001–0091 and beyond). FHIR mapping is configured via config/fhir_mappings/message_type_registry.json and config/fhir_mappings/vocabulary_maps.json. De-identification rules are defined in config/deid/default_rules.csv.

---

v0.7 Build Execution

EPIC Backlog

EPIC-001: Core Pipeline Engine

EPIC-002: Platform Web Application

EPIC-003: CLI

EPIC-004: Infrastructure and Compliance