# Архітектура медичних додатків

> Діаграми та потоки даних: пацієнт до додатка до Anpheros API до запису FHIR та зовнішніх сервісів, а також AI агент до контекстного API до авторизованих даних.

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

Anpheros — це шар медичних даних між вашим додатком (або AI агентом) та записом пацієнта. Ваш додаток зберігає власний користувацький інтерфейс та бізнес-логіку; медичний запис, згода, походження та аудит зберігаються в Anpheros і доступні через один 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)
```

## Погляд пацієнта: від особи до зовнішніх сервісів

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

## AI-погляд: від агента до авторизованих даних

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

Модель ніколи не отримує облікових даних і ніколи не викликає Anpheros самостійно; ваш додаток запитує контекст і вирішує, що надіслати моделі. Два повних приклади з викликами API: додаток для медичного ШІ в розділі [Додатки для медичного ШІ](https://developers.anpheros.com/uk/guides/ai-healthcare) та згодний агент в розділі [AI-агенти та медичні дані](https://developers.anpheros.com/uk/guides/ai-agents-medical-data). Деталі: [AI-агенти та медичні дані](https://developers.anpheros.com/uk/guides/ai-agents-medical-data), [LLM-додатки та медичні дані](https://developers.anpheros.com/uk/guides/llm-healthcare-data).

## Запис

Кожен пацієнт має один запис, що складається з ресурсів FHIR R4: `Observation` для життєво важливих показників, лабораторних результатів, симптомів та зведень щоденної активності, `Condition` та `EpisodeOfCare`, `MedicationStatement` та `MedicationAdministration`, `DocumentReference`, `Immunization`, `AllergyIntolerance` та інших — всього 26 типів, перелічених у CapabilityStatement (`GET /fhir/R4/metadata`). Немає пропрієтарної схеми для вивчення: REST API є спрощеним представленням тих самих ресурсів, з тими ж ідентифікаторами.

Нічого не перезаписується мовчки. Кожне оновлення створює нову версію (`/fhir/R4/{type}/{id}/_history`), і кожна версія записує проєкт, який її створив, та організацію, від імені якої вона була написана.

## Два способи доступу

| | Ключ API | Токен доступу OAuth |
|---|---|---|
| Вигляд | `sk_test_…` / `sk_live_…` | `at_…` |
| Використовується | вашим сервером | додатком, що діє від імені одного пацієнта |
| Бачить | пацієнтів, створених вашим проєктом | рівно одного пацієнта, в межах областей дії (scopes), наданих пацієнтом |
| Типове використання | бекенд вашого власного додатка, лабораторна система, інтеграція клініки | сторонній додаток або AI-асистент, що отримує доступ до запису, який вже має пацієнт |

Проєкт ніколи не бачить пацієнтів іншого проєкту, якщо пацієнт не надасть доступу. Кожен проєкт отримує власний ідентифікатор для однієї й тієї ж особи (pairwise ids), тому ідентифікатори не можуть бути корельовані між додатками, а запис поза вашим доступом відповідає `404`, а не `403`.

## Два середовища

Пісочниця (sandbox) та продуктивне середовище є окремими базами даних. Ключ пісочниці (`sk_test_`) фізично не може отримати доступ до реальних пацієнтів; кожен проект пісочниці отримує власну копію з 30 синтетичних пацієнтів, яку він може вільно змінювати та скидати. Продуктивні ключі (`sk_live_`) видаються перевіреним організаціям.

## Потоки даних

**Ваш додаток записує.** `POST /v1/patients/{id}/observations` з `Idempotency-Key`. Платформа зберігає FHIR `Observation`, записує `Provenance` (тип автора: patient, practitioner, device, import або ai), логує доступ і надсилає `resource.created` webhook на підписані кінцеві точки.

**Інший додаток читає за згодою.** Пацієнт схвалює це на сторінці згоди (`/oauth/authorize`), обираючи запис і тривалість (30–365 днів). Додаток обмінює код на токени та читає лише те, що дозволено областями дії (scopes). Пацієнт бачить додаток, його області дії та кожне читання у своєму журналі доступу, і може відкликати його в будь-який час.

**Лабораторія доставляє результати.** `POST /v1/patients/{id}/labs/import` з CSV, HL7 v2 ORU^R01 або JSON звітом; кожен результат стає лабораторним `Observation` з кодами LOINC, де це відомо, і повторне надсилання того ж звіту є безпечним.

**ШІ-моделі потрібен контекст.** `POST /v1/context` повертає частини запису, що стосуються завдання, в межах бюджету токенів, кожен елемент позначений джерелом; виклик записується з ідентифікатором маніфесту. Сама модель працює там, де ви обираєте.

## Місце Anpheros порівняно з самостійною розробкою

| Питання | Самостійна розробка | З Anpheros |
|---|---|---|
| Медична модель даних | проєктування таблиць для кожного типу запису | ресурси FHIR R4, 26 типів |
| Інтероперабельність | власні формати експорту | FHIR R4, International Patient Summary, SMART on FHIR |
| Згода | реалізація логіки надання, області дії, терміну дії та відкликання | гранти OAuth 2.1 відображені як FHIR `Consent` |
| Аудит | створення логування та способу його відображення пацієнтам | кожне читання та запис логуються та видимі пацієнту |
| Інтеграція лабораторій | парсинг формату кожної лабораторії | імпорт CSV, HL7 v2 ORU та JSON |
| Контекст ШІ | написання коду отримання та узагальнення | API контексту з бюджетом токенів та мітками походження |

## Пов'язане

- [Що таке Anpheros?](https://developers.anpheros.com/uk/guides/what-is-anpheros)
- [Розробка програмного забезпечення для охорони здоров'я](https://developers.anpheros.com/uk/guides/healthcare-software)
- [Бекенд та база даних медичних додатків](https://developers.anpheros.com/uk/guides/medical-app-backend)
- [Створення медичного додатку](https://developers.anpheros.com/uk/guides/build-a-healthcare-app)
- [Модель згоди та доступу](https://developers.anpheros.com/uk/guides/consent)
- [Безпека, конфіденційність та місцезнаходження даних](https://developers.anpheros.com/uk/guides/security)