# 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.

Source: https://developers.anpheros.com/guides/architecture

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](https://developers.anpheros.com/guides/ai-healthcare) and a consented agent in [AI agents and medical data](https://developers.anpheros.com/guides/ai-agents-medical-data). Details: [AI agents and medical data](https://developers.anpheros.com/guides/ai-agents-medical-data), [LLM applications and healthcare data](https://developers.anpheros.com/guides/llm-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

| | API key | OAuth access token |
|---|---|---|
| Looks like | `sk_test_…` / `sk_live_…` | `at_…` |
| Used by | your server | an application acting for one patient |
| Sees | the patients your project created | exactly one patient, within the scopes the patient granted |
| Typical use | your own app's backend, a lab system, a clinic integration | a third-party app or AI assistant reaching a record the patient already has |

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

| Concern | Building it yourself | With Anpheros |
|---|---|---|
| Medical data model | design tables for each kind of record | FHIR R4 resources, 26 types |
| Interoperability | custom export formats | FHIR R4, International Patient Summary, SMART on FHIR |
| Consent | build grant, scope, expiry and revocation logic | OAuth 2.1 grants mirrored as FHIR `Consent` |
| Audit | build logging and a way to show it to patients | every read and write logged and visible to the patient |
| Lab integration | parse each lab's format | CSV, HL7 v2 ORU and JSON import |
| AI context | write retrieval and summarisation code | context API with token budget and provenance labels |

## Related

- [What is Anpheros?](https://developers.anpheros.com/guides/what-is-anpheros)
- [Healthcare software development](https://developers.anpheros.com/guides/healthcare-software)
- [Medical app backend and database](https://developers.anpheros.com/guides/medical-app-backend)
- [Build a healthcare app](https://developers.anpheros.com/guides/build-a-healthcare-app)
- [Consent and access model](https://developers.anpheros.com/guides/consent)
- [Security, privacy and data residency](https://developers.anpheros.com/guides/security)