# Architettura delle applicazioni sanitarie

> Diagrammi e flussi di dati: dal paziente all'applicazione all'API Anpheros al record FHIR e ai servizi esterni, e dall'agente AI all'API di contesto ai dati autorizzati.

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

Anpheros è il livello dei dati medici tra la tua applicazione (o agente AI) e il record del paziente. La tua applicazione mantiene la propria interfaccia utente e logica di business; il record medico, il consenso, la provenienza e l'audit risiedono in Anpheros e sono raggiungibili tramite un'unica 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)
```

## La vista del paziente: dalla persona ai servizi esterni

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

## La vista AI: dall'agente ai dati autorizzati

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

Il modello non riceve mai credenziali e non chiama mai direttamente Anpheros; la tua applicazione richiede il contesto e decide cosa inviare al modello. Due esempi completi con le chiamate API: un'applicazione sanitaria AI in [AI healthcare applications](https://developers.anpheros.com/it/guides/ai-healthcare) e un agente con consenso in [AI agents and medical data](https://developers.anpheros.com/it/guides/ai-agents-medical-data). Dettagli: [AI agents and medical data](https://developers.anpheros.com/it/guides/ai-agents-medical-data), [LLM applications and healthcare data](https://developers.anpheros.com/it/guides/llm-healthcare-data).

## Il record

Ogni paziente ha un record composto da risorse FHIR R4: `Observation` per i segni vitali, i risultati di laboratorio, i sintomi e i riepiloghi delle attività giornaliere, `Condition` e `EpisodeOfCare`, `MedicationStatement` e `MedicationAdministration`, `DocumentReference`, `Immunization`, `AllergyIntolerance` e altri — 26 tipi in totale, elencati in tempo reale nella CapabilityStatement (`GET /fhir/R4/metadata`). Non esiste uno schema proprietario da imparare: la REST API è una vista semplificata delle stesse risorse, con gli stessi ID.

Nulla viene sovrascritto silenziosamente. Ogni aggiornamento crea una nuova versione (`/fhir/R4/{type}/{id}/_history`), e ogni versione registra il progetto che l'ha scritta e l'organizzazione per conto della quale è stata scritta.

## Due modalità di accesso

| | Chiave API | Token di accesso OAuth |
|---|---|---|
| Aspetto | `sk_test_…` / `sk_live_…` | `at_…` |
| Utilizzato da | il tuo server | un'applicazione che agisce per conto di un paziente |
| Vede | i pazienti creati dal tuo progetto | esattamente un paziente, nell'ambito degli scope concessi dal paziente |
| Uso tipico | il backend della tua applicazione, un sistema di laboratorio, un'integrazione clinica | un'applicazione di terze parti o un assistente AI che accede a un record già in possesso del paziente |

Un progetto non vede mai i pazienti di un altro progetto a meno che il paziente non conceda l'accesso. Ogni progetto ottiene il proprio identificatore per la stessa persona (ID pairwise), quindi gli ID non possono essere correlati tra applicazioni e un record al di fuori della tua portata risponde `404`, mai `403`.

## Due ambienti

Il sandbox e la produzione sono database separati. Una chiave sandbox (`sk_test_`) non può fisicamente accedere a pazienti reali; ogni progetto sandbox ottiene la propria copia di 30 pazienti sintetici, che può modificare liberamente e resettare. Le chiavi di produzione (`sk_live_`) vengono rilasciate a organizzazioni verificate.

## Flussi di dati

**La tua app scrive.** `POST /v1/patients/{id}/observations` con un `Idempotency-Key`. La piattaforma memorizza un `Observation` FHIR, scrive un `Provenance` (tipo autore: patient, practitioner, device, import o ai), registra l'accesso e invia un webhook `resource.created` agli endpoint sottoscritti.

**Un'altra applicazione legge con consenso.** Il paziente la approva sulla pagina di consenso ospitata (`/oauth/authorize`), scegliendo il record e la durata (30-365 giorni). L'applicazione scambia il codice con i token e legge solo ciò che gli scope consentono. Il paziente vede l'applicazione, i suoi scope e ogni lettura nel proprio log di accesso, e può revocarlo in qualsiasi momento.

**Un laboratorio consegna i risultati.** `POST /v1/patients/{id}/labs/import` con un report CSV, HL7 v2 ORU^R01 o JSON; ogni risultato diventa un `Observation` di laboratorio con codici LOINC dove noti, e il reinvio dello stesso report è sicuro.

**Un modello AI necessita di contesto.** `POST /v1/context` restituisce le parti del record pertinenti a un'attività, entro un budget di token, ogni elemento etichettato con la sua origine; la chiamata viene registrata con un ID manifest. Il modello stesso viene eseguito ovunque tu scelga.

## Dove si posiziona Anpheros rispetto alla creazione da zero

| Preoccupazione | Creazione da zero | Con Anpheros |
|---|---|---|
| Modello dati medico | progettare tabelle per ogni tipo di record | Risorse FHIR R4, 26 tipi |
| Interoperabilità | formati di esportazione personalizzati | FHIR R4, International Patient Summary, SMART on FHIR |
| Consenso | creare logica di concessione, ambito, scadenza e revoca | Concessioni OAuth 2.1 rispecchiate come FHIR `Consent` |
| Audit | creare logging e un modo per mostrarlo ai pazienti | ogni lettura e scrittura registrata e visibile al paziente |
| Integrazione di laboratorio | analizzare il formato di ogni laboratorio | importazione CSV, HL7 v2 ORU e JSON |
| Contesto AI | scrivere codice di recupero e riassunto | API di contesto con budget di token ed etichette di provenienza |

## Correlati

- [Cos'è Anpheros?](https://developers.anpheros.com/it/guides/what-is-anpheros)
- [Sviluppo di software sanitario](https://developers.anpheros.com/it/guides/healthcare-software)
- [Backend e database per app mediche](https://developers.anpheros.com/it/guides/medical-app-backend)
- [Creare un'app sanitaria](https://developers.anpheros.com/it/guides/build-a-healthcare-app)
- [Modello di consenso e accesso](https://developers.anpheros.com/it/guides/consent)
- [Sicurezza, privacy e residenza dei dati](https://developers.anpheros.com/it/guides/security)