# Architektura aplikacji medycznych

> Schematy i przepływy danych: pacjent do aplikacji do Anpheros API do rekordu FHIR i usług zewnętrznych, oraz agent AI do API kontekstowego do autoryzowanych danych.

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

Anpheros to warstwa danych medycznych pomiędzy Twoją aplikacją (lub agentem AI) a rekordem pacjenta. Twoja aplikacja zachowuje własny interfejs użytkownika i logikę biznesową; rekord medyczny, zgody, pochodzenie danych i audyt znajdują się w Anpheros i są dostępne poprzez jedno 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)
```

## Widok pacjenta: od osoby do usług zewnętrznych

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

## Widok AI: od agenta do autoryzowanych danych

```
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 nigdy nie otrzymuje poświadczeń i nigdy sam nie wywołuje Anpheros; Twoja aplikacja żąda kontekstu i decyduje, co wysłać do modelu. Dwa kompletne przykłady z wywołaniami API: aplikacja AI w służbie zdrowia w [Aplikacje AI w służbie zdrowia](https://developers.anpheros.com/pl/guides/ai-healthcare) i agent za zgodą w [Agenci AI i dane medyczne](https://developers.anpheros.com/pl/guides/ai-agents-medical-data). Szczegóły: [Agenci AI i dane medyczne](https://developers.anpheros.com/pl/guides/ai-agents-medical-data), [Aplikacje LLM i dane dotyczące opieki zdrowotnej](https://developers.anpheros.com/pl/guides/llm-healthcare-data).

## Rekord

Każdy pacjent ma jeden rekord składający się z zasobów FHIR R4: `Observation` dla parametrów życiowych, wyników badań laboratoryjnych, objawów i podsumowań codziennej aktywności, `Condition` i `EpisodeOfCare`, `MedicationStatement` i `MedicationAdministration`, `DocumentReference`, `Immunization`, `AllergyIntolerance` i innych — łącznie 26 typów, wymienionych na żywo w CapabilityStatement (`GET /fhir/R4/metadata`). Nie ma potrzeby uczenia się własnościowego schematu: REST API jest uproszczonym widokiem tych samych zasobów, z tymi samymi identyfikatorami.

Nic nie jest nadpisywane bez powiadomienia. Każda aktualizacja tworzy nową wersję (`/fhir/R4/{type}/{id}/_history`), a każda wersja rejestruje projekt, który ją zapisał, oraz organizację, w imieniu której została zapisana.

## Dwie drogi dostępu

| | Klucz API | Token dostępu OAuth |
|---|---|---|
| Wygląda jak | `sk_test_…` / `sk_live_…` | `at_…` |
| Używane przez | Twój serwer | Aplikację działającą w imieniu jednego pacjenta |
| Widzi | Pacjentów utworzonych przez Twój projekt | Dokładnie jednego pacjenta, w zakresie uprawnień przyznanych przez pacjenta |
| Typowe zastosowanie | Backend Twojej własnej aplikacji, system laboratoryjny, integracja kliniczna | Aplikacja zewnętrzna lub asystent AI uzyskujący dostęp do rekordu, który pacjent już posiada |

Projekt nigdy nie widzi pacjentów innego projektu, chyba że pacjent udzieli dostępu. Każdy projekt otrzymuje własny identyfikator dla tej samej osoby (identyfikatory parami), dzięki czemu identyfikatory nie mogą być korelowane między aplikacjami, a rekord poza Twoim zasięgiem odpowiada `404`, nigdy `403`.

## Dwa środowiska

Środowisko piaskownicy (sandbox) i produkcyjne to oddzielne bazy danych. Klucz piaskownicy (`sk_test_`) fizycznie nie ma dostępu do prawdziwych pacjentów; każdy projekt w piaskownicy otrzymuje własną kopię 30 syntetycznych pacjentów, którą może dowolnie modyfikować i resetować. Klucze produkcyjne (`sk_live_`) są wydawane zweryfikowanym organizacjom.

## Przepływy danych

**Twoja aplikacja zapisuje.** `POST /v1/patients/{id}/observations` za pomocą `Idempotency-Key`. Platforma przechowuje `Observation` FHIR, zapisuje `Provenance` (typ autora: pacjent, praktyk, urządzenie, import lub AI), loguje dostęp i wysyła webhook `resource.created` do subskrybowanych punktów końcowych.

**Inna aplikacja odczytuje za zgodą.** Pacjent zatwierdza ją na hostowanej stronie zgody (`/oauth/authorize`), wybierając rekord i czas trwania (30–365 dni). Aplikacja wymienia kod na tokeny i odczytuje tylko to, na co pozwalają zakresy (scopes). Pacjent widzi aplikację, jej zakresy i każde odczytanie w swoim dzienniku dostępu i może je w dowolnym momencie odwołać.

**Laboratorium dostarcza wyniki.** `POST /v1/patients/{id}/labs/import` z raportem w formacie CSV, HL7 v2 ORU^R01 lub JSON; każdy wynik staje się wynikiem laboratoryjnym `Observation` z kodami LOINC, jeśli są znane, a ponowne wysłanie tego samego raportu jest bezpieczne.

**Model AI potrzebuje kontekstu.** `POST /v1/context` zwraca części rekordu istotne dla zadania, w ramach budżetu tokenów, każdy element oznaczony źródłem; wywołanie jest rejestrowane z identyfikatorem manifestu. Sam model działa tam, gdzie wybierzesz.

## Gdzie Anpheros wypada w porównaniu z budowaniem własnego rozwiązania

| Zagadnienie | Budowanie własnego rozwiązania | Z Anpheros |
|---|---|---|
| Model danych medycznych | projektowanie tabel dla każdego rodzaju rekordu | zasoby FHIR R4, 26 typów |
| Interoperacyjność | niestandardowe formaty eksportu | FHIR R4, International Patient Summary, SMART on FHIR |
| Zgoda | budowanie logiki przyznawania, zakresu, wygaśnięcia i cofania | granty OAuth 2.1 odzwierciedlone jako FHIR `Consent` |
| Audyt | budowanie logowania i sposobu jego prezentacji pacjentom | każde odczytanie i zapis są logowane i widoczne dla pacjenta |
| Integracja z laboratorium | parsowanie formatu każdego laboratorium | import CSV, HL7 v2 ORU i JSON |
| Kontekst AI | pisanie kodu pobierania i podsumowywania | API kontekstu z budżetem tokenów i etykietami pochodzenia |

## Powiązane tematy

- [Czym jest Anpheros?](https://developers.anpheros.com/pl/guides/what-is-anpheros)
- [Tworzenie oprogramowania dla branży medycznej](https://developers.anpheros.com/pl/guides/healthcare-software)
- [Backend i baza danych aplikacji medycznych](https://developers.anpheros.com/pl/guides/medical-app-backend)
- [Tworzenie aplikacji medycznej](https://developers.anpheros.com/pl/guides/build-a-healthcare-app)
- [Model zgody i dostępu](https://developers.anpheros.com/pl/guides/consent)
- [Bezpieczeństwo, prywatność i lokalizacja danych](https://developers.anpheros.com/pl/guides/security)