# Architektura zdravotnické aplikace

> Diagramy a datové toky: pacient do aplikace do Anpheros API do záznamu FHIR a externích služeb, a AI agent do kontextového API do autorizovaných dat.

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

Anpheros je vrstva lékařských dat mezi vaší aplikací (nebo AI agentem) a záznamem pacienta. Vaše aplikace si ponechává své vlastní uživatelské rozhraní a obchodní logiku; lékařský záznam, souhlas, původ a audit žijí v Anpheros a jsou přístupné prostřednictvím jednoho 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)
```

## Pohled pacienta: od osoby k externím službám

```
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)
```

## Pohled AI: od agenta k autorizovaným datům

```
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
```

Model nikdy neobdrží přihlašovací údaje a nikdy sám nezavolá Anpheros; vaše aplikace si vyžádá kontext a rozhodne, co pošle modelu. Dva kompletní příklady s API voláními: aplikace AI pro zdravotnictví v [AI healthcare applications](https://developers.anpheros.com/cs/guides/ai-healthcare) a souhlasný agent v [AI agents and medical data](https://developers.anpheros.com/cs/guides/ai-agents-medical-data). Podrobnosti: [AI agents and medical data](https://developers.anpheros.com/cs/guides/ai-agents-medical-data), [LLM applications and healthcare data](https://developers.anpheros.com/cs/guides/llm-healthcare-data).

## Záznam

Každý pacient má jeden záznam složený z FHIR R4 zdrojů: `Observation` pro vitální funkce, laboratorní výsledky, symptomy a souhrny denní aktivity, `Condition` a `EpisodeOfCare`, `MedicationStatement` a `MedicationAdministration`, `DocumentReference`, `Immunization`, `AllergyIntolerance` a další – celkem 26 typů, uvedených živě v CapabilityStatement (`GET /fhir/R4/metadata`). Neexistuje žádné proprietární schéma, které byste se museli učit: REST API je jednodušší pohled na stejné zdroje, se stejnými ID.

Nic není tiše přepsáno. Každá aktualizace vytvoří novou verzi (`/fhir/R4/{type}/{id}/_history`) a každá verze zaznamenává projekt, který ji zapsal, a organizaci, jejímž jménem byla zapsána.

## Dva způsoby přístupu

| | API klíč | OAuth přístupový token |
|---|---|---|
| Vypadá jako | `sk_test_…` / `sk_live_…` | `at_…` |
| Používá | váš server | aplikace jednající za jednoho pacienta |
| Vidí | pacienty, které váš projekt vytvořil | přesně jednoho pacienta, v rámci rozsahů udělených pacientem |
| Typické použití | backend vaší vlastní aplikace, laboratorní systém, integrace kliniky | aplikace třetí strany nebo AI asistent přistupující k záznamu, který pacient již má |

Projekt nikdy neuvidí pacienty jiného projektu, pokud pacient neudělí přístup. Každý projekt získá pro stejnou osobu vlastní identifikátor (párové ID), takže ID nelze korelovat napříč aplikacemi a záznam mimo váš dosah odpoví `404`, nikdy `403`.

## Dvě prostředí

Sandbox a produkční prostředí jsou oddělené databáze. Sandbox klíč (`sk_test_`) se fyzicky nemůže dostat k reálným pacientům; každý sandbox projekt získá svou vlastní kopii 30 syntetických pacientů, kterou může libovolně měnit a resetovat. Produkční klíče (`sk_live_`) jsou vydávány ověřeným organizacím.

## Datové toky

**Vaše aplikace zapisuje.** `POST /v1/patients/{id}/observations` s `Idempotency-Key`. Platforma uloží FHIR `Observation`, zapíše `Provenance` (typ autora: patient, practitioner, device, import nebo ai), zaznamená přístup a odešle `resource.created` webhook na přihlášené koncové body.

**Jiná aplikace čte se souhlasem.** Pacient ji schválí na hostované stránce souhlasu (`/oauth/authorize`), přičemž vybere záznam a dobu trvání (30–365 dnů). Aplikace si vymění kód za tokeny a čte pouze to, co umožňují rozsahy (scopes). Pacient vidí aplikaci, její rozsahy a každý čtení ve svém přístupovém protokolu a může jej kdykoli odvolat.

**Laboratoř dodává výsledky.** `POST /v1/patients/{id}/labs/import` s reportem ve formátu CSV, HL7 v2 ORU^R01 nebo JSON; každý výsledek se stane laboratorním `Observation` s kódy LOINC, pokud jsou známy, a opětovné odeslání stejného reportu je bezpečné.

**AI model potřebuje kontext.** `POST /v1/context` vrátí části záznamu relevantní pro daný úkol, v rámci rozpočtu tokenů, přičemž každá položka je označena svým zdrojem; volání je zaznamenáno s ID manifestu. Samotný model běží kdekoli si vyberete.

## Kam Anpheros zapadá ve srovnání s vlastním vývojem

| Aspekt | Vlastní vývoj | S Anpherosem |
|---|---|---|
| Datový model pro zdravotnická data | návrh tabulek pro každý typ záznamu | FHIR R4 zdroje, 26 typů |
| Interoperabilita | vlastní exportní formáty | FHIR R4, International Patient Summary, SMART on FHIR |
| Souhlas | implementace logiky pro udělení, rozsah, platnost a odvolání | OAuth 2.1 granty zrcadlené jako FHIR `Consent` |
| Audit | implementace logování a způsobu jeho zobrazení pacientům | každé čtení a zápis je logováno a viditelné pro pacienta |
| Integrace laboratoří | parsování formátu každé laboratoře | import CSV, HL7 v2 ORU a JSON |
| Kontext pro AI | napsání kódu pro načítání a sumarizaci | kontextové API s rozpočtem tokenů a štítky původu |

## Související

- [Co je Anpheros?](https://developers.anpheros.com/cs/guides/what-is-anpheros)
- [Vývoj softwaru ve zdravotnictví](https://developers.anpheros.com/cs/guides/healthcare-software)
- [Backend a databáze pro lékařské aplikace](https://developers.anpheros.com/cs/guides/medical-app-backend)
- [Vytvoření zdravotnické aplikace](https://developers.anpheros.com/cs/guides/build-a-healthcare-app)
- [Model souhlasu a přístupu](https://developers.anpheros.com/cs/guides/consent)
- [Zabezpečení, ochrana soukromí a rezidence dat](https://developers.anpheros.com/cs/guides/security)