# Architektúra zdravotníckej aplikácie

> Diagramy a dátové toky: pacient do aplikácie do Anpheros API do záznamu FHIR a externých služieb, a AI agent do kontextového API do autorizovaných dát.

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

Anpheros je vrstva lekárskych dát medzi vašou aplikáciou (alebo AI agentom) a záznamom pacienta. Vaša aplikácia si zachováva vlastné používateľské rozhranie a obchodnú logiku; lekársky záznam, súhlas, pôvod a audit žijú v Anpheros a sú prístupné prostredníctvom jedného 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)
```

## Pohľad 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)
```

## Pohľad AI: od agenta k autorizovaným dátam

```
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 nedostane poverenia a nikdy sám nevykoná volanie Anpheros; vaša aplikácia si vyžiada kontext a rozhodne, čo pošle modelu. Dva kompletné príklady s volaniami API: aplikácia AI v zdravotníctve v časti [Aplikácie AI v zdravotníctve](https://developers.anpheros.com/sk/guides/ai-healthcare) a súhlasný agent v časti [AI agenti a lekárske dáta](https://developers.anpheros.com/sk/guides/ai-agents-medical-data). Podrobnosti: [AI agenti a lekárske dáta](https://developers.anpheros.com/sk/guides/ai-agents-medical-data), [LLM aplikácie a zdravotnícke dáta](https://developers.anpheros.com/sk/guides/llm-healthcare-data).

## Záznam

Každý pacient má jeden záznam zložený z FHIR R4 zdrojov: `Observation` pre vitálne funkcie, laboratórne výsledky, symptómy a denné súhrny aktivít, `Condition` a `EpisodeOfCare`, `MedicationStatement` a `MedicationAdministration`, `DocumentReference`, `Immunization`, `AllergyIntolerance` a ďalšie — celkovo 26 typov, uvedených naživo v CapabilityStatement (`GET /fhir/R4/metadata`). Neexistuje žiadny proprietárny schéma, ktoré by ste sa museli učiť: REST API je zjednodušený pohľad na tie isté zdroje, s tými istými ID.

Nič sa prepisuje potichu. Každá aktualizácia vytvorí novú verziu (`/fhir/R4/{type}/{id}/_history`) a každá verzia zaznamenáva projekt, ktorý ju zapísal, a organizáciu, v mene ktorej bola zapísaná.

## Dva spôsoby prístupu

| | API kľúč | OAuth prístupový token |
|---|---|---|
| Vzhľad | `sk_test_…` / `sk_live_…` | `at_…` |
| Používa | váš server | aplikácia konajúca v mene jedného pacienta |
| Vidí | pacientov, ktorých váš projekt vytvoril | presne jedného pacienta, v rámci rozsahov, ktoré pacient povolil |
| Typické použitie | backend vašej vlastnej aplikácie, laboratórny systém, integrácia kliniky | aplikácia tretej strany alebo AI asistent pristupujúci k záznamu, ktorý pacient už má |

Projekt nikdy neuvidí pacientov iného projektu, pokiaľ pacient neudelí prístup. Každý projekt dostane vlastný identifikátor pre tú istú osobu (párové ID), takže ID nie je možné korelovať medzi aplikáciami a záznam mimo vášho dosahu odpovie `404`, nikdy `403`.

## Dve prostredia

Sandbox a produkcia sú oddelené databázy. Sandbox kľúč (`sk_test_`) sa fyzicky nemôže dostať k reálnym pacientom; každý sandbox projekt dostane svoju vlastnú kópiu 30 syntetických pacientov, ktorú môže voľne meniť a resetovať. Produkčné kľúče (`sk_live_`) sú vydávané overeným organizáciám.

## Toky dát

**Vaša aplikácia zapisuje.** `POST /v1/patients/{id}/observations` pomocou `Idempotency-Key`. Platforma uloží FHIR `Observation`, zapíše `Provenance` (typ autora: pacient, praktikant, zariadenie, import alebo AI), zaznamená prístup a odošle `resource.created` webhook na prihlásené koncové body.

**Iná aplikácia číta so súhlasom.** Pacient ju schváli na hostovanej stránke súhlasu (`/oauth/authorize`), pričom vyberie záznam a trvanie (30 – 365 dní). Aplikácia si vymení kód za tokeny a číta iba to, čo povolia rozsahy (scopes). Pacient vidí aplikáciu, jej rozsahy a každé čítanie vo svojom denníku prístupov a môže ho kedykoľvek odvolať.

**Laboratórium doručuje výsledky.** `POST /v1/patients/{id}/labs/import` s reportom vo formáte CSV, HL7 v2 ORU^R01 alebo JSON; každý výsledok sa stane laboratórnym `Observation` s LOINC kódmi, ak sú známe, a opätovné odoslanie rovnakého reportu je bezpečné.

**AI model potrebuje kontext.** `POST /v1/context` vráti časti záznamu relevantné pre úlohu, v rámci rozpočtu tokenov, pričom každá položka je označená svojím zdrojom; volanie sa zaznamená s ID manifestu. Samotný model beží kdekoľvek si vyberiete.

## Kde Anpheros zapadá v porovnaní s vlastným vývojom

| Obava | Vlastný vývoj | S Anpheros |
|---|---|---|
| Model lekárskych údajov | návrh tabuliek pre každý typ záznamu | FHIR R4 zdroje, 26 typov |
| Interoperabilita | vlastné exportné formáty | FHIR R4, International Patient Summary, SMART on FHIR |
| Súhlas | vytvorenie logiky pre udelenie, rozsah, platnosť a odvolanie | OAuth 2.1 granty zrkadlené ako FHIR `Consent` |
| Audit | vytvorenie logovania a spôsobu jeho zobrazenia pacientom | každé čítanie a zápis zaznamenané a viditeľné pre pacienta |
| Integrácia laboratória | parsovanie formátu každého laboratória | import CSV, HL7 v2 ORU a JSON |
| AI kontext | napísanie kódu na načítanie a sumarizáciu | kontextové API s rozpočtom tokenov a štítkami pôvodu |

## Súvisiace

- [Čo je Anpheros?](https://developers.anpheros.com/sk/guides/what-is-anpheros)
- [Vývoj zdravotníckeho softvéru](https://developers.anpheros.com/sk/guides/healthcare-software)
- [Backend a databáza pre zdravotnícke aplikácie](https://developers.anpheros.com/sk/guides/medical-app-backend)
- [Vytvorenie zdravotníckej aplikácie](https://developers.anpheros.com/sk/guides/build-a-healthcare-app)
- [Model súhlasu a prístupu](https://developers.anpheros.com/sk/guides/consent)
- [Bezpečnosť, ochrana súkromia a lokalita údajov](https://developers.anpheros.com/sk/guides/security)