Documentation

Technical reference: data model, graph schema, sources, functions, workflows, security and API.

Architecture overview

How the Atlas layers fit together.

Alphiniti Atlas is a React single-page application served from the platform, backed by managed entity storage and serverless functions. Every screen reads and writes entity records through the authenticated SDK; anything that needs a secret, a long-running job or a third-party API runs in a backend function.

A Neo4j graph sits alongside the relational data and holds the relationship model — providers, organizations, trials, specialties and conditions, and the edges between them. The graph is written by sync and linking jobs, and read by the network and explorer screens.

Scheduled workflows drive the ingestion and scoring pipeline. They call backend functions in sequence, resuming long jobs in chunks, so a full national refresh completes over several runs instead of one long request.

Layers

Presentation: React + Vite pages under the router, one route per screen, lazy-loaded. Shared UI from the component library, styling from design tokens.
Application services: Backend functions (HTTP handlers) for syncs, scoring builders, linkers, exports, AI calls and integrations.
Entity storage: Managed records for providers, facilities, trials, scores, engagement, compliance and operations data.
Graph store: Neo4j instance holding the relationship model, queried read-only by the explorer and network screens.
Orchestration: Workflows: scheduled, entity-triggered and webhook-triggered runs that chain the functions above.

Data model

The entity catalogue, grouped by what it describes.

Every entity is a JSON schema with typed, optionally enumerated fields. All records carry the built-in id, created_date, updated_date and created_by_id attributes; sync jobs stamp their own sync date fields so freshness is always visible on the record.

Access is enforced per entity with row-level rules (see Security), which is why some records are readable by every signed-in user while writes stay administrator-only.

Providers and facilities

Provider: NPPES identity: NPI, name, credential, gender, enumeration type and status, primary specialty and taxonomy code, Medicare acceptance, enumeration and certification dates, source and sync date.
NpiProvider: Raw NPPES registry mirror used by lookups and refreshes, with NpiRefreshLog recording each refresh run.
ProviderLocation: Practice addresses per NPI: address lines, city, state, ZIP, county, phone, fax, location type, latitude and longitude.
ProviderAffiliation: Provider-to-facility privileges with the facility identity used for site resolution.
Organization: Hospitals and facilities keyed by CMS certification number: name, type, ownership, profit status, bed count, CMS rating, accreditation and geography.
HospitalMetric: Quality and process measures per facility, one row per measure with its value, period and comparison.
NursingHome, HomeHealthAgency: Post-acute facility records from their respective CMS datasets.
PayerParticipation: Which payers each facility or provider participates with, used by Payer Reports.
Specialty, TaxonomyCode: Reference lists behind every specialty filter, including NUCC taxonomy descriptions and groupings.

Clinical research

ClinicalTrial: ClinicalTrials.gov study: NCT id, title, status and previous status, phase, study type, conditions, interventions, sponsor, enrollment, dates, eligibility, locations and counts. Also carries the investigator resolution fields — investigator name, affiliation, linked NPI, link status/confidence/score and linked hospital CCNs.
TrialSiteFeasibility: Per-site feasibility score built from enrollment history, competing trials in the region and investigator benchmarks.
LiteratureIntelligence: Emerging topics, evidence summaries and a lightweight evidence graph of genes, drugs, diseases and biomarkers with relation types and confidence.
BibliometricAnalytics: Author, journal, citation-network, altmetric and institution metrics.
Drug: Drug reference records from FDA sources, used to interpret prescriber and payment data.

Scoring and analytics

KolProfile, KolScoreHistory: Current KOL score and tier per provider, plus every previous score so trends are visible.
OpportunityScore, PredictiveScore: Engagement opportunity ranking and forward-looking influence or region projections.
ScientificVoice: Share of voice per provider and therapeutic area, with trend direction and sponsor affiliations.
CollaborationLink: Provider-to-provider collaboration edges with type, shared trials, shared organizations, shared sponsors and a strength value.
DiseaseEpidemiology: Burden, mortality breakdown, trial density, market gap and forecast rows per disease and geography.
PatientJourney: Treatment pathway flows, care gaps, timelines and lines of therapy.
TerritoryPlanning: Territory alignment, field activity, coverage gaps and travel routes with workload, coverage, gap and priority scores.
KolEngagement: Meetings, advisory boards, speaking and consulting engagements with Sunshine Act payment categories, compliance status and influence-decay risk.
CompetitiveIntel, RealWorldEvidence: Competitor profiles, pipeline assets, trial comparisons, patent cliffs and conferences; plus cohorts, comparative effectiveness, safety signals and external control arms.
PrescriberStat: Medicare Part D claims, beneficiaries and drug cost per provider, drug and year — the input to prescriber matching.
DashboardStats: Daily warehouse counts used by the dashboard so it does not aggregate on every visit.

Collaboration and operations

Project, UserProject, SavedItem, CollaborationComment: Projects, membership, saved providers/hospitals/trials and field-level comments with author attribution.
AuditLog: Append-only record of create, read, update, delete, sign and export events with field-level before/after values, reason, source and session metadata.
CmsSyncJob, CmsDataset, NpiRefreshLog, ProviderLookupLog: Sync job tracking, dataset registry, refresh history and provider lookup telemetry.
MortalityRecord, GlobalHealthIndicator: CDC Wonder mortality and WHO/World Bank health indicators behind the epidemiology and global health screens.
HubInboundMessage: Messages received from the connected Hub application: type, source, correlation id, consent reference, disposition and full envelope.
UserProfile: Per-user preferences and profile details layered on the built-in User entity. Roles are limited to admin and user.

Graph schema

Nodes, edges and what populates them.

The graph is the relationship store. Nodes are keyed by natural identifiers — NPI for providers, CMS certification number for organizations, NCT id for trials — so repeated syncs merge rather than duplicate.

Nodes

Provider: Key: npi. Properties include name, specialty, state, KOL tier and score, publications and trial counts. Placeholder nodes are created when an edge references an NPI not yet enriched.
Organization: Key: org_id (CMS CCN). Properties include name, ownership, profit status, hospital type, CMS rating and geography.
ClinicalTrial: Key: nct_id. Properties include title, phase, status, sponsor and enrollment.
Specialty, Condition: Reference nodes created from provider taxonomies and trial conditions.

Edges

AFFILIATED_WITH: Provider → Organization. Hospital privileges, streamed from the CMS affiliation feed (~2.28M rows) with type, source and updated_at. Stale edges are pruned after a full pass.
INVESTIGATED_BY: ClinicalTrial → Provider. Written only for unambiguous investigator name matches, with the match score retained on the trial record.
AT_SITE: ClinicalTrial → Organization. Trial locations resolved to facilities by normalized city and state.
PRACTICES: Provider → Specialty, from the provider taxonomy.
STUDIES: ClinicalTrial → Condition, from the trial’s condition list.
COLLABORATES_WITH: Provider → Provider. Stored collaboration records plus, in the explorer, derived edges between two providers who share a hospital.

Reading coverage

In view vs in graph: Explorer stats return both the counts inside the rendered slice (edges_by_type) and whole-graph totals (graph_edges_by_type), so a zero can be distinguished from a narrow filter.
Degree: Each node carries its degree in the current view; the highest-degree node is surfaced as the hub of the slice.
Bounds: Queries cap seed nodes per layer and total nodes and edges, keeping response time predictable at the cost of completeness — raise the per-type limit for a wider slice.

Data sources and refresh

Where each dataset comes from and how often it lands.

Federal and registry sources

NPPES (CMS NPI registry): Provider identities and practice addresses. Nightly, split into state batches and driven by a dispatcher.
CMS Care Compare — hospitals: Facility identity, ownership, certification and location. Nightly, resumable chunks, deduplicated by CCN.
CMS Care Compare — hospital affiliations: Provider privilege pairs (~2.28M rows), streamed in chunks into AFFILIATED_WITH edges, with stale-edge pruning after the pass.
CMS quality measures: Facility quality and process measures per reporting period.
CMS nursing homes and home health agencies: Post-acute facility records, refreshed every six hours.
CMS Part D prescriber data: Claims, beneficiaries and drug cost per provider — the base of prescriber analytics and trial matching.
CMS Open Payments: Industry payments to physicians, folded into KOL scoring and engagement views.
CMS payer participation: Payer coverage per facility, refreshed on a six-hour cycle.
ClinicalTrials.gov: Study registry with status change history, refreshed nightly with change auditing.
PubMed / NCBI E-utilities: Publications and citation data behind publication counts and literature intelligence.
CDC Wonder: Mortality records used for burden and epidemiological views.
WHO GHO and World Bank HNP: Global health indicators for the global health dashboard.
FDA drug data: Drug reference records.

Operational notes

Freshness: Each record carries its own sync date; the Sync Dashboard shows the last successful run per source. Nightly sources trail live systems by up to a day.
Chunking: Large national files are processed with a start-row cursor: each run returns next_row and done, and the workflow continues on the following step or night.
Geocoding: Addresses are geocoded in batches; records without coordinates are simply not plotted yet.

Backend functions

The serverless functions, grouped by job.

Functions are the only place secrets are used. Each one validates its caller — an administrator session or the shared X-API-Key header — before doing work, and returns a JSON summary with counts, so a run can be audited from its response.

Sync and ingestion

nppesSync / nppesSyncOptimized: Paginated NPPES ingestion; the optimized path batches writes and handles large states.
hospitalSync: CMS hospital ingestion with CCN deduplication, state scoping and resumable batches.
atlasSyncOrganizations, atlasSyncHospitalMetrics, atlasSyncQualityMeasures: Facility identity, metrics and quality measures.
atlasSyncProviderAffiliations: Streams the CMS affiliations CSV into graph edges; supports stats_only, dry_run and prune_before.
atlasSyncProviderLocations, atlasSyncSpecialty, atlasSyncNursingHomes, atlasSyncHomeHealth: Locations, specialty taxonomy and post-acute facilities.
atlasSyncPartD, atlasSyncPayerParticipation, prescriberSync: Prescriber claims, payer coverage and prescriber profiles.
atlasSyncCdcWonder, atlasSyncWorldBankHnp, whoGhoSync, fdaDrugSync: Mortality, global indicators and drug reference data.
clinicalTrialsSync, auditClinicalTrialChange: Trial registry refresh and the append-only change audit for status transitions.
atlasSyncHospitalGeography: Backfills state and region on facility nodes for regional analytics.
atlasSyncDispatcher, atlasSyncHospitalDispatcher: Fan-out controllers that start the per-state or per-dataset runs.
cmsDatasetSync, taxonomyCodeSync, qualitySync, qualityMeasureSync: Dataset registry, taxonomy and quality reference loads.

Linking and enrichment

atlasLinkTrialNpis: Resolves trial investigator names to provider NPIs; writes linked, ambiguous or no_match with a confidence score, and reports per-run metrics.
linkTrialsToProviders, linkTrialsToHospitals: Provider-to-trial and trial-to-facility linking by name and by normalized city/state.
matchTrialsToProvider: Ranks trials against one provider’s prescribing profile for the trial matcher.
collaborationNetworkBuilder: Builds provider-to-provider collaboration edges from shared sponsors and organizations.
geocodeAddresses, geocodeHospitalLocations, geocodeProviderLocations, batchGeocodeProviderLocations: Batch geocoding, single and bulk.
flagStaleProviderLocations, monitorPrescriberStatAnomalies, territoryGapAlertChecker, alertTrialProviderMatch: Detectors that raise alerts for staleness, outliers, coverage gaps and new trial matches.

Scoring, analytics and builders

atlasScoreKol, kolScoringScheduler, kolSync, kolSyncOptimized: KOL scoring runs and the scheduler that batches them.
opportunityScoring, predictiveScoring, scientificVoiceScoring: Opportunity, predictive and share-of-voice scores.
trialSiteFeasibilityBuilder, bibliometricAnalyticsBuilder, diseaseEpidemiologyBuilder, literatureIntelligenceBuilder, competitiveIntelBuilder, rweAnalysisBuilder, patientJourneyBuilder, territoryPlannerBuilder, kolEngagementBuilder: One builder per intelligence dashboard; each recomputes its entity rows for a therapeutic area.
calculateDashboardStats, getProviderStateCounts, getPrescriberStatCount, getMapProviders: Aggregates and map payloads so screens do not scan large tables client-side.
bigqueryKolAnalysis: Warehouse query for publication-heavy cohorts.
aiResearchAssistant, weeklyKolReport: AI research answers and the weekly report assembly.

Graph, data access and platform

neo4jSync: Writes entity records into graph nodes and edges; optional schema setup and dry run.
neo4jGraphQuery, hospitalNetworkMap: Read-only graph queries: layered explorer slices with edge totals, and regional facility network data.
getEntityData, getEntitySchema, exportEntityData: Bounded read, schema introspection and CSV/JSON export of entity data.
secureEntityAccess: Role-aware entity access checks used by sensitive reads.
getGoogleMapsKey, testGoogleMapsKey: Map key delivery and validation.
driveBackup, cleanupOldSyncJobs: Google Drive snapshots and sync-job housekeeping.
hubSendMessage, hubReceiveMessage, hubPublishEvidence, hubIssueConsentReference: Hub interoperability: outbound messages, inbound webhook with consent checks, evidence publication and consent references.
sendContactMessage, githubSprintIssues, clickupSprint, createPursuitClickUpTask: Contact form delivery, GitHub issue sync, ClickUp task sync and pursuit task creation.

Workflows and schedules

What runs automatically, and when.

Nightly

NPPES sync (nationwide + state batches + dispatcher): Provider identity and address refresh, split into six regional batches to stay inside runtime limits.
HospitalOrganization Sync, Atlas Nightly Hospital Dispatcher: Facility refresh in resumable chunks.
Provider Affiliations Sync: Full affiliation pass in chunks, then stale-edge pruning so privileges that ended are removed.
Clinical Trials Sync, Atlas Nightly Clinical Trials Sync: Registry refresh, with changed-status trials written to the audit trail.
Atlas Nightly Trial-Provider Linking: Investigator-to-NPI linking, then trial site-to-facility linking, then the new relationships written to the graph.
Atlas Nightly KOL Scoring, KOL Scoring — Batch Scheduler, Atlas KOL Nightly Scoring: Score recalculation across the provider base.
Atlas Nightly Prescriber Sync, Dashboard Stats — Daily Refresh: Part D refresh and the daily aggregate counts.
Daily Sync Job Cleanup, Daily Drive Backup, Daily Drive Data Snapshot: Housekeeping and backup.

Every six hours

Nursing Homes Sync, Home Health Sync, Payer Participation Sync, Provider Locations Sync: Frequent sources that change often enough to justify a shorter cycle.

Weekly and event-driven

Weekly KOL Score Report, Weekly Prescriber Stat Anomaly Monitor: Scheduled reporting and anomaly detection.
Monthly Stale ProviderLocation Audit: Flags addresses that have not been confirmed recently.
Audit Clinical Trial Changes: Triggered when a trial record is updated, writing the field-level change.
Alert on New Trial — Provider Location Match, Territory Gap Alert Monitor: Event and scheduled alerts.
Create ClickUp Task for Flagged Providers: Pushes flagged providers into the ClickUp backlog.
Atlas to Hub Research Evidence: Publishes curated evidence to the connected Hub application.
Specialty Taxonomy Sync, Quality Measures Sync, Hospital Metrics Dispatcher, CDC Wonder MortalityRecord Backfill: Reference and backfill jobs.

Security and access

Roles, record-level rules, keys and audit.

Authentication and roles

Identity: Accounts are managed by the platform. There are two roles: admin and user. Administrators can manage users and see all records; standard users see their own work plus shared reference data.
Row-level rules: Every entity declares create, read, update and delete rules. Reference data such as providers, facilities, trials and specialities is readable by any signed-in user; writes are administrator-only. Personal and operational records (projects, comments, audit logs, hub messages) are restricted to their owner or an administrator.
Client scope: Screens use the user-scoped SDK client so rules apply. Service-role access is confined to backend functions that need to write bulk data.

API and secrets

Function authentication: Functions accept an administrator session or the shared API key presented in the X-API-Key header. Keys are never read from the request body, and comparisons are constant-time.
Secrets: Neo4j connection values, the Atlas API key, encryption key, NCBI key, Google OAuth client credentials, the Google Maps key and the Hub shared secrets are stored as platform secrets and read only inside functions.
Field-level encryption: Sensitive fields pass through the shared encryption module before storage; decryption happens server-side.

Audit and integrity

Audit trail: Every create, update, delete and export writes an AuditLog entry with user, timestamp, field-level before/after values, reason and source. Entries are append-only.
Change triggers: Trial updates are audited by a dedicated trigger so status history is complete even for automated syncs.
Compliance reports: Printable reports assemble the trail for a period, formatted for review and retention.

Integrations

External services the platform talks to.

Connected services

Neo4j Aura: Graph store, reached over the HTTPS Query API with parameterised statements; credentials come from secrets.
Google Maps: Mapping and geocoding for the map screens, with the key delivered by a function rather than embedded in the bundle.
Google BigQuery: Warehouse queries for the KOL analysis screen.
Google Drive: Backup destination for daily data snapshots.
GitHub: Issue sync for the sprint dashboard.
ClickUp: Task creation and sprint tracking.
Alphiniti Hub: Cross-application messaging: outbound messages, consented inbound webhook, evidence publication and consent references.
NCBI / PubMed: Publication and citation lookups.

AI

Assistants: The SuperAgent plus domain advisors for disease intelligence, territory optimization, nursing homes, clinical trials, KOL analysis, KOL outreach, trial opportunity and project status.
Research assistant: Server-side AI calls with the app’s curated context; answers cite the stored data they were built from.

API and function reference

How to call the platform programmatically.

Backend functions are invoked over HTTP at /functions/<functionName> on the app’s host. JSON in, JSON out. The shared API key travels in the X-API-Key header — never in the body.

Request shape

Method and headers: POST with Content-Type: application/json and X-API-Key: <key>. An authenticated administrator session is accepted in place of the key.
Response envelope: Successful calls return ok: true with the run summary (counts, cursor position, timing). Failures return ok: false with an error message and an HTTP status.
Idempotency: Sync calls are safe to retry: writes merge on natural keys (NPI, CCN, NCT id) rather than inserting duplicates, and a cursor lets you resume from a known row.

Representative calls

neo4jGraphQuery: { layers: ["providers","hospitals","trials"], limit: 80, search: "oncology", ongoing: true } → nodes, edges and stats including per-type totals for the slice and for the whole graph.
atlasSyncProviderAffiliations: { start_row, max_rows, dry_run } → next_row and done for resumable passes; { stats_only: true } for current coverage; { prune_older_than_hours } to remove unrefreshed edges.
atlasLinkTrialNpis: { limit } → trials examined, linked, ambiguous and unmatched counts.
neo4jSync: { entities: ["ClinicalTrial","CollaborationLink"], batch_size } → nodes and edges written per entity.
getEntityData / exportEntityData: Bounded entity reads and CSV/JSON export, with the same authentication rules.
hospitalNetworkMap: Regional facility network payload with cross-region provider reach.

Scoring models

What each score is built from.

Scores are deterministic functions of stored evidence, recalculated by scheduled jobs and stamped with a calculation time. They rank attention; they are not predictions of clinical outcome, and they should be read alongside the underlying record.

Scores

KOL score (0–100) and tier: Combines publication volume, clinical trial involvement and industry payment activity, then bands the result into Elite, Senior, Rising or Emerging. History is retained per run so the trend is visible.
Opportunity score: Ranks providers by how much value engagement could unlock, using their activity, influence and current relationship depth.
Predictive score: Projects forward-looking influence and highlights high-potential regions from historical trajectories.
Share of voice: A provider’s publication and trial footprint relative to their therapeutic-area peer group, with trend direction and sponsor affiliations.
Site feasibility (0–100): Blends site enrollment history, the density of competing trials in the region and investigator benchmark performance.
Burden, trial density and market gap: Burden from mortality and DALY data; density from trial counts per condition and geography; gap from the ratio between the two.
Collaboration strength: Weighted count of shared trials, organizations and sponsors between two providers.
Trial match confidence: Name-match score for investigator resolution plus a therapeutic-overlap score for provider-to-trial matching.

Environments and releases

Production, test data, and what publishing changes.

Data environments

Production: The live database behind the published app. Screens read and write here by default.
Test: A separate database for exercising changes safely. Switch to it in the builder before running risky syncs or destructive tests.

Deployment

Publishing: Publishing from the editor promotes the current app code, including backend functions and workflows, to the live app. Unpublished function changes do not affect the live endpoint.
Schedules: Workflow schedules run against production. A newly enabled schedule starts on its next due time, not retroactively.
Integrity checks: Data Health on the admin systems page summarises record counts, duplicate facilities and unsynced sources after a release.

Glossary

Terms used across the product.

Terms

NPI: National Provider Identifier — the unique 10-digit number for a US provider or organization.
CCN: CMS Certification Number — the identifier for a Medicare-certified facility, used as the facility key throughout.
NCT id: The ClinicalTrials.gov registry identifier for a study.
KOL: Key Opinion Leader — a provider whose publications, trials and standing make them influential in a therapeutic area.
KOL tier: The band a KOL score falls into: Elite, Senior, Rising or Emerging.
Taxonomy: The NUCC classification of provider specialties and subspecialties.
Part D: Medicare’s prescription drug programme; its prescriber file supplies claims, beneficiaries and drug cost.
Open Payments: The CMS programme reporting industry payments to physicians and teaching hospitals.
Sunshine Act category: The payment classification used when logging engagements: consulting, travel, meals, research, royalty, honorarium, education or other.
Affiliation: A provider’s hospital privileges — the edge that connects a provider to a facility.
DALY / QALY: Disability-adjusted and quality-adjusted life years, used in burden analysis.
Attribution: Assigning an activity, payment or trial to the provider or facility it belongs to.
Row-level security: Per-entity rules deciding which records a user may create, read, update or delete.
Slice: The bounded set of records the explorer currently renders — distinct from the whole graph.

New to Atlas? Start with the Help Guide for task-by-task steps.