# Arquitetura de aplicações de saúde

> Diagramas e fluxos de dados: do paciente para a aplicação, para a API Anpheros, para o registo FHIR e serviços externos, e do agente de IA para a API de contexto para dados autorizados.

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

Anpheros é a camada de dados médicos entre a sua aplicação (ou agente de IA) e o registo do paciente. A sua aplicação mantém a sua própria interface de utilizador e lógica de negócio; o registo médico, consentimento, proveniência e auditoria residem em Anpheros e são acedidos através de uma 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)
```

## A vista do paciente: da pessoa a serviços externos

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

## A visão da IA: do agente aos dados autorizados

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

O modelo nunca recebe credenciais e nunca chama o Anpheros diretamente; a sua aplicação solicita o contexto e decide o que enviar para o modelo. Dois exemplos completos com as chamadas à API: uma aplicação de saúde com IA em [Aplicações de saúde com IA](https://developers.anpheros.com/pt/guides/ai-healthcare) e um agente consentido em [Agentes de IA e dados médicos](https://developers.anpheros.com/pt/guides/ai-agents-medical-data). Detalhes: [Agentes de IA e dados médicos](https://developers.anpheros.com/pt/guides/ai-agents-medical-data), [Aplicações LLM e dados de saúde](https://developers.anpheros.com/pt/guides/llm-healthcare-data).

## O registo

Cada doente tem um registo composto por recursos FHIR R4: `Observation` para sinais vitais, resultados de laboratório, sintomas e resumos de atividade diária, `Condition` e `EpisodeOfCare`, `MedicationStatement` e `MedicationAdministration`, `DocumentReference`, `Immunization`, `AllergyIntolerance` e outros — 26 tipos no total, listados em tempo real na CapabilityStatement (`GET /fhir/R4/metadata`). Não há um esquema proprietário para aprender: a API REST é uma vista mais simples dos mesmos recursos, com os mesmos IDs.

Nada é substituído silenciosamente. Cada atualização cria uma nova versão (`/fhir/R4/{type}/{id}/_history`), e cada versão regista o projeto que a escreveu e a organização em nome de quem foi escrita.

## Duas formas de acesso

| | Chave API | Token de acesso OAuth |
|---|---|---|
| Aparência | `sk_test_…` / `sk_live_…` | `at_…` |
| Utilizado por | o seu servidor | uma aplicação que atua em nome de um paciente |
| Vê | os pacientes que o seu projeto criou | exatamente um paciente, dentro dos âmbitos que o paciente concedeu |
| Uso típico | o backend da sua própria aplicação, um sistema de laboratório, uma integração clínica | uma aplicação de terceiros ou um assistente de IA a aceder a um registo que o paciente já possui |

Um projeto nunca vê os pacientes de outro projeto, a menos que o paciente conceda acesso. Cada projeto obtém o seu próprio identificador para a mesma pessoa (identificadores par-a-par), pelo que os identificadores não podem ser correlacionados entre aplicações, e um registo fora do seu alcance responde com `404`, nunca com `403`.

## Dois ambientes

A sandbox e a produção são bases de dados separadas. Uma chave de sandbox (`sk_test_`) não consegue, fisicamente, aceder a pacientes reais; cada projeto de sandbox recebe a sua própria cópia de 30 pacientes sintéticos, que pode alterar livremente e repor. As chaves de produção (`sk_live_`) são emitidas para organizações verificadas.

## Fluxos de dados

**A sua aplicação escreve.** `POST /v1/patients/{id}/observations` com um `Idempotency-Key`. A plataforma armazena um `Observation` FHIR, escreve um `Provenance` (tipo de autor: paciente, praticante, dispositivo, importação ou IA), regista o acesso e envia um webhook `resource.created` para os endpoints subscritos.

**Outra aplicação lê com consentimento.** O paciente aprova-o na página de consentimento alojada (`/oauth/authorize`), escolhendo o registo e a duração (30–365 dias). A aplicação troca o código por tokens e lê apenas o que os escopos permitem. O paciente vê a aplicação, os seus escopos e cada leitura no seu registo de acesso, podendo revogá-lo a qualquer momento.

**Um laboratório entrega resultados.** `POST /v1/patients/{id}/labs/import` com um relatório CSV, HL7 v2 ORU^R01 ou JSON; cada resultado torna-se um `Observation` de laboratório com códigos LOINC quando conhecidos, e reenviar o mesmo relatório é seguro.

**Um modelo de IA necessita de contexto.** `POST /v1/context` devolve as partes do registo relevantes para uma tarefa, dentro de um orçamento de tokens, cada item rotulado com a sua origem; a chamada é registada com um ID de manifesto. O próprio modelo é executado onde quer que escolha.

## Onde o Anpheros se encaixa em comparação com a construção do zero

| Preocupação | Construção do zero | Com Anpheros |
|---|---|---|
| Modelo de dados médicos | desenhar tabelas para cada tipo de registo | Recursos FHIR R4, 26 tipos |
| Interoperabilidade | formatos de exportação personalizados | FHIR R4, International Patient Summary, SMART on FHIR |
| Consentimento | construir lógica de concessão, âmbito, expiração e revogação | Concessões OAuth 2.1 espelhadas como FHIR `Consent` |
| Auditoria | construir registos e uma forma de os mostrar aos pacientes | cada leitura e escrita registada e visível para o paciente |
| Integração de laboratório | analisar o formato de cada laboratório | Importação CSV, HL7 v2 ORU e JSON |
| Contexto de IA | escrever código de recuperação e sumarização | API de contexto com orçamento de tokens e rótulos de proveniência |

## Relacionado

- [O que é Anpheros?](https://developers.anpheros.com/pt/guides/what-is-anpheros)
- [Desenvolvimento de software de saúde](https://developers.anpheros.com/pt/guides/healthcare-software)
- [Backend e base de dados de aplicações médicas](https://developers.anpheros.com/pt/guides/medical-app-backend)
- [Criar uma aplicação de saúde](https://developers.anpheros.com/pt/guides/build-a-healthcare-app)
- [Modelo de consentimento e acesso](https://developers.anpheros.com/pt/guides/consent)
- [Segurança, privacidade e residência de dados](https://developers.anpheros.com/pt/guides/security)