Healthcare application architecture

Diagrams and data flows: patient to application to Anpheros API to the FHIR record and external services, and AI agent to the context API to authorised data.

Anpheros is the medical-data layer between your application (or AI agent) and the patient's record. Your application keeps its own user interface and business logic; the medical record, consent, provenance and audit live in Anpheros and are reached through one API.

  Your application, backend or AI agent
  (mobile app, web app, clinic system, lab system, LLM-based assistant)
                        │  HTTPS · API key (sk_test_ / sk_live_) or OAuth token (at_…)
                        ▼
  Anpheros Platform API
  ├─ /v1        simplified REST: patients, observations, conditions, medications,
  │             documents, timeline, provenance, context, labs, webhooks
  ├─ /fhir/R4   strict FHIR R4: 26 resource types, search, history, transactions,
  │             $everything, $summary (IPS), $validate
  └─ /oauth     OAuth 2.1 + PKCE, SMART on FHIR, OpenID Connect
                        │  every request: project isolation · scopes · rate limits
                        ▼
  One FHIR R4 record per patient
  ├─ versions of every resource (history)   ├─ Provenance for every write
  ├─ Consent resources for every grant      └─ access log visible to the patient
                        │
                        ▼
  Events out: signed webhooks to your server (ids only, never clinical content)

The patient's view: from person to external services

Patient
   ↓   uses an app, chooses what to share, sees every access
Healthcare application          Anpheros Daily, or your own app
   ↓   REST v1 / FHIR R4 over HTTPS, API key or OAuth token
Anpheros API
   ↓   isolation, scopes, idempotency, provenance
FHIR medical data               the patient's record: 26 resource types, every version kept
   ↓   only what the patient allowed, only for as long as allowed
External healthcare services    laboratories (lab import), clinics (directory, acting-as),
                                other apps (OAuth / SMART), your backend (webhooks)

The AI view: from agent to authorised data

AI agent or LLM application     runs the model you choose — hosted or local
   ↓   POST /v1/context  {patient, task, question, budget_tokens}
Medical context API             plans which parts of the record matter, fits them into the budget,
   ↓                            labels every item with author type and source, records a manifest
Authorised medical data         only records the project created or the patient granted;
                                the read appears in the patient's access log

The model never receives credentials and never calls Anpheros itself; your application requests the context and decides what to send to the model. Two complete examples with the API calls: an AI healthcare application in AI healthcare applications and a consented agent in AI agents and medical data. Details: AI agents and medical data, LLM applications and healthcare data.

The record

Every patient has one record made of FHIR R4 resources: Observation for vital signs, lab results, symptoms and daily activity summaries, Condition and EpisodeOfCare, MedicationStatement and MedicationAdministration, DocumentReference, Immunization, AllergyIntolerance and others — 26 types in all, listed live in the CapabilityStatement (GET /fhir/R4/metadata). There is no proprietary schema to learn: the REST API is a simpler view of the same resources, with the same ids.

Nothing is silently overwritten. Each update creates a new version (/fhir/R4/{type}/{id}/_history), and each version records the project that wrote it and the organisation on whose behalf it was written.

Two ways in

A project never sees another project's patients unless the patient grants access. Each project gets its own identifier for the same person (pairwise ids), so ids cannot be correlated across applications, and a record outside your reach answers 404, never 403.

Two environments

The sandbox and production are separate databases. A sandbox key (sk_test_) physically cannot reach real patients; each sandbox project gets its own copy of 30 synthetic patients, which it can change freely and reset. Production keys (sk_live_) are issued to verified organisations.

Data flows

Your app writes. POST /v1/patients/{id}/observations with an Idempotency-Key. The platform stores a FHIR Observation, writes a Provenance (author type: patient, practitioner, device, import or ai), logs the access and sends a resource.created webhook to subscribed endpoints.

Another application reads with consent. The patient approves it on the hosted consent page (/oauth/authorize), choosing the record and the duration (30–365 days). The application exchanges the code for tokens and reads only what the scopes allow. The patient sees the application, its scopes and every read in their access log, and can revoke it at any time.

A lab delivers results. POST /v1/patients/{id}/labs/import with a CSV, HL7 v2 ORU^R01 or JSON report; every result becomes a laboratory Observation with LOINC codes where known, and re-sending the same report is safe.

An AI model needs context. POST /v1/context returns the parts of the record relevant to a task, within a token budget, each item labelled with its source; the call is recorded with a manifest id. The model itself runs wherever you choose.

Where Anpheros fits compared with building it yourself

Related

• What is Anpheros?
• Healthcare software development
• Medical app backend and database
• Build a healthcare app
• Consent and access model
• Security, privacy and data residency