# Medical app backend and database

> What a medical app backend and its database must handle, which parts Anpheros provides as a managed healthcare database, what stays in your backend, three ways to connect, and how to stay in sync with webhooks.

Source: https://developers.anpheros.com/guides/medical-app-backend

**A medical app backend is the server side of a healthcare application: it stores patient data, enforces who may see it, keeps a history of changes and talks to labs, clinics and other services.** With Anpheros, the medical part of that backend — the healthcare database that holds each patient's record, with its history, consent, provenance, audit, lab import and events — is provided by the platform through an API, and your own backend keeps only what is specific to your product.

## What a medical backend has to handle

| Responsibility | Why it is hard in healthcare | With Anpheros |
|---|---|---|
| A medical data model | dozens of kinds of data, each with standard codes | HL7 FHIR R4, 26 resource types, LOINC / ICD-10 / ATC / UCUM |
| Versioning | medical data is corrected, never silently overwritten | every update is a new version; `If-Match` for conditional updates |
| Documents | originals must stay unchanged and traceable | immutable originals with SHA-256, EU storage encrypted with a customer-managed key |
| Access control | per patient, per application, per data type | project isolation, pairwise ids, OAuth scopes with category filters |
| Consent | the patient decides, and can change their mind | grants for 30–365 days, revocable, mirrored as FHIR `Consent` |
| Audit | patients and regulators ask who saw what | every read and write logged and visible to the patient |
| Provenance | a value from a lab is not a value typed by a patient | author type, organisation, practitioner and source system on every write |
| Integrations | labs send CSV, HL7 v2, JSON; apps need events | lab import, FHIR transactions, signed webhooks |
| Safe retries | a duplicated medication or result is a clinical error | `Idempotency-Key` on every create |
| Test data | real patients must never be in development | a sandbox database with synthetic patients |

## What stays in your backend

- your **users and accounts**, and the mapping from each user to their Anpheros patient id (the pairwise id your project sees);
- **product data** that is not medical: settings, subscriptions, content, reminders' schedules;
- **business rules** — which of your staff may see which patient in your product;
- the **API key**, which must never be shipped inside a mobile or web app.

## Three ways to connect

**1. Your backend holds the API key (most common).** Your app calls your backend; your backend calls Anpheros with an `sk_live_` key and sees the patients your project created.

```ts
import { Anpheros, apiKey } from '@anpheros/sdk';
const anpheros = new Anpheros({ auth: apiKey(process.env.ANPHEROS_KEY!) });

// GET /api/me/vitals in your backend, after your own authentication
export async function myVitals(user: { anpherosPatientId: string }) {
  const page = await anpheros.observations.list(user.anpherosPatientId, { category: 'vital-signs', limit: 50 });
  return page.data;
}
```

**2. The app acts for the patient with OAuth.** For people who already have an Anpheros record, a mobile or web app is a *public* OAuth client with PKCE: the person consents on the hosted page and the app receives a 30-minute access token and a rotating refresh token for that one record. The SDKs implement the flow (`OAuthFlow`).

**3. Server-to-server partners.** A confidential client (with a secret, kept on a server) can use the authorization-code flow, or `client_credentials`, which behaves like an API key for that project.

## Keeping your backend in sync

Subscribe to webhooks instead of polling. Deliveries are signed (`Anpheros-Signature`, HMAC-SHA256 over timestamp and body), at-least-once and possibly out of order; de-duplicate by event id and ignore stale versions.

```ts
import { verifyWebhookSignature } from '@anpheros/sdk';

app.post('/anpheros/hook', express.raw({ type: 'application/json' }), async (req, res) => {
  const ok = await verifyWebhookSignature({ secret: process.env.ANPHEROS_WEBHOOK_SECRET!, header: req.header('anpheros-signature'), body: req.body });
  if (!ok) return res.status(400).end();
  const event = JSON.parse(req.body.toString());   // ids and versions only — read the resource if you need it
  res.status(204).end();
});
```

## Handling errors and limits

- Treat `404` as "not visible to you", never as proof that a record does not exist.
- `403` means the credential exists but may not do this — a missing scope, or a resource written by another organisation.
- `429` comes with `Retry-After`; the SDKs wait and retry automatically, as they do for `5xx`.
- Keep the `Anpheros-Request-Id` of failed calls for support.

[Errors](https://developers.anpheros.com/guides/errors) · [Limits and rate limits](https://developers.anpheros.com/guides/limits)

## Frequently asked questions

### What database should a medical app use?
One that keeps medical data in a standard, versioned form and controls access per patient. Anpheros is a managed healthcare database built on HL7 FHIR R4: each patient's record is versioned and searchable, every write carries provenance, and an application sees a patient only if it created the record or the patient consented. Your own database keeps the rest of your product's data — accounts, billing, content.

### Is there a free database for medical apps?
Yes. The Anpheros sandbox is free: sign in with Google, get a key in one click, and your project gets its own 30 synthetic patients and up to 10 000 writes a day. Production starts at €49 a month for 2,500 patients, with the first month free; production access is for verified organisations with a signed data processing agreement. See [Pricing](https://developers.anpheros.com/guides/pricing).

### Can I keep real patient data in the free sandbox?
No. The sandbox is for synthetic data only: each sandbox project gets its own synthetic patients, and sandbox keys cannot reach production. Real patient records belong in a production project.

## Related

- [Healthcare software development](https://developers.anpheros.com/guides/healthcare-software)
- [Build a healthcare app](https://developers.anpheros.com/guides/build-a-healthcare-app)
- [Architecture](https://developers.anpheros.com/guides/architecture)
- [Medical data API](https://developers.anpheros.com/guides/medical-data-api)
- [SDKs](https://developers.anpheros.com/guides/sdks)