​

Arquitetura do Sistema — Meu PACS Cloud

​

Sumário

1. Visão Geral
2. Stack e Tecnologias
3. Serviços Docker e Portas
4. Variáveis de Ambiente
5. Volumes Compartilhados
6. Fluxo de Ingestão DICOM
7. Orthanc — Servidor PACS
8. Backend — API Laravel
9. Worker Python — Processamento de Imagens
10. Multi-Tenant e RBAC
11. Sistema de Laudos
12. OHIF Viewer — Visualizador DICOM
13. Frontend — Next.js
14. Proxy CORS do Orthanc
15. Como Editar Cada Parte
16. Arquitetura Alvo — Orthanc On-Premise com Forwarding

​

1. Visão Geral

[Aparelho DICOM]
      │ C-STORE (DICOM protocol)
      ▼
[Orthanc :4242]  ←── armazena as imagens DICOM brutas
      │ Lua hook (OnStableStudy)
      │ POST /api/orthanc/webhook
      ▼
[Backend Laravel :8000]  ←── API REST, autenticação JWT, regras de negócio
      │ Redis queue (pacs_python_queue)
      ▼
[Worker Python]  ←── gera thumbnail, indexa series/instances no Postgres
      │
      ▼
[PostgreSQL :5432]  ←── banco de dados de todos os metadados

[Frontend Next.js :3000]  ←── interface do usuário
      │ usa API do backend
      │ abre OHIF com token temporário
      ▼
[OHIF Viewer :3001]  ←── visualizador DICOM no browser
      │ DicomWeb requests (QIDO-RS, WADO-RS)
      ▼
[Nginx CORS Proxy :8043]  ←── valida token, repassa ao Orthanc
      │
      ▼
[Orthanc :8042 (HTTP)]  ←── serve as imagens DICOM via DicomWeb

​

2. Stack e Tecnologias

​

3. Serviços Docker e Portas

Nota: O Orthanc expõe a porta HTTP 8042 apenas dentro da rede Docker — não é acessível diretamente do host. O acesso externo passa pelo proxy 8043.

Produção: o docker-compose.prod.yml adiciona o container pacs_caddy (Caddy 2 Alpine) nas portas 80:80 e 443:443 como reverse proxy com TLS automático. Não existe em dev.

​

4. Variáveis de Ambiente

​

.env (raiz) — Infraestrutura Docker

DB_DATABASE=pacs_database
DB_USERNAME=pacs_admin
DB_PASSWORD=...

REDIS_HOST=redis
REDIS_PORT=6379

ORTHANC_WEBHOOK_SECRET=dev-webhook-secret-change-in-prod

​

backend/.env — Configuração do Laravel

APP_ENV=local          # local | production
APP_DEBUG=true         # false em produção

ORTHANC_URL=http://orthanc:8042          # endereço interno do Orthanc
ORTHANC_WEBHOOK_SECRET=dev-...           # deve bater com o do Orthanc

DB_CONNECTION=pgsql
DB_HOST=postgres
DB_PORT=5432
DB_DATABASE=pacs_database
DB_USERNAME=pacs_admin
DB_PASSWORD=...

SESSION_DRIVER=redis
QUEUE_CONNECTION=redis
CACHE_STORE=redis

REDIS_HOST=redis
REDIS_PORT=6379

JWT_SECRET=...         # gerado com: php artisan jwt:secret

Importante: As variáveis DB_* do worker Python vêm do .env raiz (não do backend/.env). Se o worker não indexar series/instances, verifique se essas variáveis estão no .env raiz.

​

5. Volumes Compartilhados

/app/storage/thumbnails/{orthanc_study_id}/preview.jpg

/app/pacs_mount/thumbnails/{orthanc_study_id}/preview.jpg

​

6. Fluxo de Ingestão DICOM

​

Modelo atual (desenvolvimento / testes)

1. Aparelho envia via DICOM C-STORE → Orthanc :4242 (exposto publicamente)

2. Orthanc acumula as imagens do estudo.
   Após 10 segundos sem novas imagens (StableAge=10), considera "estável".

3. Orthanc executa o hook Lua (OnStableStudy):
   → POST http://backend:8000/api/orthanc/webhook
   → Header: X-Webhook-Secret: [secret]
   → Body: {"ID": "orthanc-study-uuid"}

4. Backend (WebhookController):
   → Valida o X-Webhook-Secret
   → Despacha o job ProcessStudyMetadata para a fila Redis padrão do Laravel

5. Backend (ProcessStudyMetadata job — executa assincronamente):
   → GET http://orthanc:8042/studies/{id}         → metadados do estudo
   → GET http://orthanc:8042/series/{id}           → primeira série
   → GET http://orthanc:8042/instances/{id}/metadata/RemoteAET → AET de quem enviou

   → Modality::where('aet', $remoteAet)->first()  → resolve Tenant + Unit
   → Se não encontrar AET cadastrado: estudo vai para tenant "quarentena"

   → Cria/atualiza o registro Study no PostgreSQL (com tenant_id + unit_id)
   → Enfileira payload enxuto no Redis (fila pacs_python_queue para o worker Python)

6. Worker Python (main.py — consome pacs_python_queue via BLPOP):
   → Gera thumbnail 300×300 JPEG da primeira imagem DICOM
   → Salva em /app/storage/thumbnails/{orthanc_study_id}/preview.jpg
   → Indexa Patient, Series, Instances no PostgreSQL
   → Atualiza modalities[] no Study

​

Modelo alvo (produção com VPN)

1. Aparelho envia via DICOM C-STORE → Orthanc Local (rede interna da clínica)

2. Orthanc local armazena e faz forwarding para o cloud via túnel VPN

3. Cloud Orthanc :4242 recebe — RemoteAET = AET do Orthanc local (ex: "CLINICA_A_U1")
   (não mais o AET do aparelho físico)

4-6. Fluxo idêntico ao modelo atual a partir do passo 3 →
   O `ProcessStudyMetadata` faz lookup do RemoteAET na tabela `modalities`
   → Cada entrada em `modalities` representa agora um Orthanc local (gateway),
     não um aparelho físico individual

​

Resolução de Tenant/Unit — detalhe crítico

$remoteAet = $orthancService->getRemoteAET($instanceId);
// → GET /instances/{id}/metadata/RemoteAET

$maquina = Modality::where('aet', $remoteAet)->first();
$tenant  = $maquina->tenant;
$unitId  = $maquina->unit_id;

• Se o AET não estiver cadastrado em modalities → estudo vai para tenant quarentena.
• Todo novo gateway (Orthanc local) precisa ter seu AET cadastrado no painel antes de começar a enviar.

​

7. Orthanc — Servidor PACS

​

O que é

​

Arquivos de configuração

​

orthanc.json — principais configurações

{
  "HttpPort": 8042,          // Porta HTTP (interna Docker)
  "DicomPort": 4242,         // Porta DICOM (exposta ao host)
  "DicomAet": "ORTHANC",     // Nome AET deste servidor
  "AuthenticationEnabled": false,  // Sem auth na rede interna (usar proxy para expor)
  "StableAge": 10,           // Segundos sem novas imagens para considerar estável
  "DicomWeb": {
    "Enable": true,
    "Root": "/dicom-web"     // Base URL da API DicomWeb
  },
  "LuaScripts": ["/tmp/hook.lua"]  // Script gerado no entrypoint
}

​

Hook Lua

function OnStableStudy(studyId, tags, metadata)
    local payload = '{"ID": "' .. studyId .. '"}'
    local headers = {}
    headers["Content-Type"] = "application/json"
    headers["X-Webhook-Secret"] = "${ORTHANC_WEBHOOK_SECRET}"
    HttpPost("http://backend:8000/api/orthanc/webhook", payload, headers)
end

​

Endpoints do Orthanc usados pelo backend

​

8. Backend — API Laravel

​

Estrutura

• Framework: Laravel 12 com Octane (servidor RoadRunner)
• Autenticação: JWT (tymon/jwt-auth) via cookie pacs_access_token
• Banco: Eloquent ORM com PostgreSQL
• Filas: Redis (queue padrão do Laravel + pacs_python_queue manual)

backend/
  app/
    Http/Controllers/    # 13 controllers
    Http/Middleware/     # EnsureSuperAdmin, EnsureTenantAdmin, SetBearerFromCookie
    Jobs/                # ProcessStudyMetadata
    Models/              # 12 modelos Eloquent
    Services/            # OrthancService
    Traits/              # BelongsToTenant, BelongsToTenantAndUnit
  config/
    cors.php             # CORS com supports_credentials=true, allowed_origins via FRONTEND_URL
  routes/
    api.php              # Todas as rotas da API

​

Reload após mudanças PHP

docker exec pacs_backend php artisan octane:reload
# ou
docker compose restart backend

​

Mapa completo de rotas

​

Públicas (sem autenticação)

​

Protegidas por JWT (auth:api)

​

Qualquer usuário autenticado do tenant — prefixo /api/tenant (leitura)

​

Qualquer usuário autenticado do tenant — leitura adicional

​

Tenant Admin (auth:api + tenant_admin) — prefixo /api/tenant

​

Super Admin (auth:api + super_admin) — prefixo /api/admin

​

Comunicação Backend → Orthanc

Backend → http://orthanc:8042/...

​

9. Worker Python — Processamento de Imagens

​

O que faz

1. Gera thumbnail — baixa o DICOM bruto do Orthanc, extrai o pixel array, normaliza para 8-bit, salva como JPEG 300×300
2. Indexa Patient — upsert atômico por (tenant_id, patient_id)
3. Indexa Series — para cada série do estudo (busca Orthanc)
4. Indexa Instances — para cada imagem de cada série
5. Atualiza modalities — array de modalidades distintas no estudo

​

Localização

worker/main.py     # Arquivo único de toda a lógica

​

Endpoints do Orthanc usados pelo worker

​

Variáveis de ambiente

REDIS_HOST: redis
ORTHANC_URL: http://orthanc:8042
DEBUG_WORKER: 1          # Ativa logs detalhados (desativar em prod)
DB_HOST: postgres
DB_PORT: 5432
DB_DATABASE: ${DB_DATABASE}   # vem do .env raiz
DB_USERNAME: ${DB_USERNAME}   # vem do .env raiz
DB_PASSWORD: ${DB_PASSWORD}   # vem do .env raiz

​

10. Multi-Tenant e RBAC

​

Hierarquia

Tenant (clínica)
  └── Unit (filial/unidade)
        └── User (médico, recepcionista, admin)
        └── Modality (gateway Orthanc local)
        └── Study (exame)
              └── Series
                    └── Instance (imagem DICOM)
              └── Report (laudo)

​

Roles — modelo de negócio

​

O que cada role pode fazer

• Criar e gerenciar clínicas (tenants)
• Criar e gerenciar unidades dentro das clínicas
• Criar e gerenciar todos os usuários (de qualquer tenant)
• Cadastrar gateways Orthanc locais (modalities + AET + vpn_ip)
• Provisionar WireGuard por unidade
• Acessar o painel clínico de qualquer tenant

• Visualizar estudos e pacientes da clínica
• Gerenciar templates de laudo (criar, editar, ativar/desativar por unidade)
• Gerenciar presets de laudo (criar, editar, filtrar por modalidade)
• Gerenciar usuários → responsabilidade do Super Admin
• Gerenciar unidades → responsabilidade do Super Admin
• Não pode criar, editar ou corrigir laudos — POST /studies/{id}/reports e POST /studies/{id}/reports/corrections retornam 403

• Visualizar estudos e pacientes da sua unidade
• Escrever, finalizar e corrigir laudos

Histórico: a Fase 1 da refatoração de roles (remover gerenciamento de users/units do tenant admin, consolidando em super admin) foi concluída. A Fase 2 original (redesign do painel super admin) foi substituída pelo refactor de memberships — ver docs/MEMBERSHIPS_REFACTOR.md para o modelo multi-vínculo que permite um usuário trabalhar em múltiplas clínicas/unidades.

​

Como o scoping funciona automaticamente

static::addGlobalScope('tenant', function (Builder $builder) {
    // Super admin: vê tudo
    if (Auth::check() && Auth::user()->is_super_admin) return;

    // Outros: filtra pelo tenant_id do JWT
    if (Auth::check() && Auth::user()->tenant_id) {
        $builder->where('tenant_id', Auth::user()->tenant_id);
    }
});

​

JWT Claims

• tenant_id — qual clínica
• unit_id — qual unidade
• is_super_admin — flag booleano
• is_tenant_admin — flag booleano

​

11. Sistema de Laudos

​

Conceitos

• Template — Define a estrutura visual do laudo (ReportTemplateLayoutV1): regiões (header/footer heights, body padding), slots posicionados em % (logo, paciente, assinatura), tipografia (fonte, tamanhos). Obrigatoriamente vinculado a uma unidade (unit_id required). Uma unidade tem no máximo um template ativo — ao ativar um novo, os outros são desativados automaticamente. Não tem template_id no preset.
• Preset — Modelo de texto reutilizável para um tipo de exame (default_content em HTML Tiptap). Recurso do tenant inteiro — unit_id é sempre null; qualquer médico de qualquer unidade da mesma clínica pode usar. O template visual (papel timbrado, layout) vem sempre da unidade do médico logado, não do preset. Filtrado no painel pelo médico pela modalidade do estudo. Sugestão automática por study_description_contains e/ou modality.
• Report — O laudo em si, vinculado a um Study. O campo content armazena HTML gerado pelo Tiptap. Apenas usuários regulares (doutores) podem criar e editar laudos — tenant admins e super admins recebem 403 nas rotas de escrita; podem apenas visualizar.
• ReportRevision — Auditoria imutável. Toda ação gera uma revisão com previous_content e new_content em HTML.

​

Editor de template (/tenant/templates)

% = mm × 100 / dimensão_página
mm = (% / 100) × dimensão_página   (PAGE_W = 210mm, PAGE_H = 297mm)

1. Validada no frontend: file.type deve ser image/png ou image/jpeg (rejeita antes de ler o arquivo)
2. Carregada em um <canvas>
3. Fundo branco preenchido antes do drawImage — evita que áreas transparentes de PNGs virem preto no JPEG
4. Redimensionada para no máximo 1240×1754px (A4@150dpi)
5. Exportada como JPEG 75%
6. Armazenada como base64 no campo assets JSONB do template

• PNG de entrada → saída PNG (preserva transparência — essencial para logos com fundo transparente e assinaturas sobre papel)
• JPEG de entrada → fundo branco + JPEG (evita fundo preto)

​

Resolução automática de template e preset

Template → GET /tenant/my-template
         → retorna template ativo cuja unit_id = unit_id do usuário logado
         → aplicado automaticamente no PDF

Preset → sugestão por matching (do mais específico ao mais genérico):
  1. study_description_contains bate E modalidade bate
  2. Só study_description_contains bate
  3. Só modalidade bate
  4. Primeiro preset ativo (fallback)

​

Editor Rich Text (Tiptap)

• Componente: frontend/components/ui/rich-text-editor.tsx
• Extensões: StarterKit (bold, italic, strike, listas, headings, undo/redo) + Placeholder
• Armazenamento: HTML string no campo content / default_content
• Read-only: laudo finalizado trava o editor principal; correções têm editor separado
• PDF: HTML é parseado por parseHtmlToBlocks() (DOMParser) e renderizado com fonte e estilo preservados via renderHtmlBlocks() — nunca convertido para texto puro

​

Estados do laudo

pending → draft → final
                     ↓
                correction (permanece "final", nova revisão)

​

Fluxo de criação

POST /studies/{id}/reports  com status="draft"
    → Cria Report com status=draft
    → Cria ReportRevision com action="draft_created"

POST /studies/{id}/reports  com status="final"
    → Atualiza Report com status=final, finalized_at=now()
    → Cria ReportRevision com action="finalized"

POST /studies/{id}/reports/corrections  com content + reason
    → Requer laudo já "final"
    → Cria ReportRevision com action="correction", previous_content, new_content, reason

​

Drawer de preview ao vivo

• Botão contextual muda de texto conforme o estado: “Pré-visualizar laudo” (sem rascunho) / “Ver rascunho” / “Ver laudo final”
• Drawer desliza pela direita (680px), fecha clicando fora ou no X
• Renderiza ReportTemplateA4Preview com template da unidade + conteúdo atual em tempo real
• Mostra nome real da unidade, nome real do paciente, assinatura e CRM do autor
• Export PDF só aparece após finalização — rascunho não pode ser exportado

​

Paginação multi-página no preview

┌─ outer clip (bodyH inteiro, overflow:hidden) ───────────────┐
│  [0..effectivePadPx] → fundo branco da página (top padding) │
│  ┌─ inner clip (top=effectivePadPx, h=segmentPx) ──────────┐│
│  │  content div: top = -breaks[N]px                         ││
│  │  → breaks[N] aparece em 0 do inner → effectivePadPx visual││
│  │  → inner clip termina em breaks[N+1] → sem vazamento     ││
│  └──────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────┘

• Página 0: outer clip com altura = segmento desta página; paddingTop no content div cria o espaço superior.
• Páginas N > 0: outer clip com bodyH inteiro; inner clip começa em effectivePadPx (criando espaço branco visual = top padding equivalente ao resetBodyCursor() do PDF) e tem altura = segmentPx = breaks[N+1] - breaks[N]. O content div posiciona em top: -breaks[N]px relativo ao inner clip — exato começo do segmento desta página, sem vazar conteúdo da página anterior.

​

Export PDF com imagens

1. Modal abre (ImageSelectionModal) com cards de série — thumbnail por série (gerado pelo worker)
2. Expandir série → frames individuais via GET /studies/{id}/instances/{instanceId}/rendered (proxy Orthanc + JWT)
3. Seleção por série inteira ou frames individuais; configuração de colunas (1–6), formato (A4/A3), máx. frames/série
4. Loading com barra de progresso em duas fases (loading imagens → gerando PDF)
5. PDF gerado por study-report-pdf.ts (async) com layout do template aplicado (header/footer/slots/tipografia) + imagens embutidas
6. PDF abre em nova aba (doc.output("bloburl"))

​

Pipeline de geração de PDF — detalhes técnicos

​

Layout das páginas de imagens

​

Imagens renderizadas — sem cache

1. Backend valida JWT e escopo de tenant
2. Faz proxy para GET {ORTHANC_URL}/instances/{orthanc_id}/rendered
3. Orthanc lê o arquivo DICOM bruto do seu storage e converte para JPEG on-the-fly
4. Backend retorna com Cache-Control: no-cache, private — browser não armazena
5. Frontend recebe o blob, converte para base64, usa e descarta

​

Modalidades DICOM disponíveis nos presets

​

12. OHIF Viewer — Visualizador DICOM

​

Como funciona

​

Modos de abertura do viewer

​

Fluxo de token (compartilhado pelos dois modos)

1. Usuário clica em qualquer botão de viewer na página do estudo

2. Frontend faz:
   POST /api/viewer/token  { study_id: "uuid" }
   → Backend cria UUID no Redis com TTL 600s
   → Retorna { token: "uuid-token" }

3a. Nova aba: window.open(ohifUrl + token)
3b. Split view: <iframe src={ohifUrl + token} /> na mesma página

4. OHIF (aba ou iframe) carrega app-config.js que:
   → Lê o token da URL (window.location.search — funciona em iframe pois window = contexto do iframe)
   → Persiste no sessionStorage
   → Patcha XMLHttpRequest e fetch para injetar X-Viewer-Token em toda requisição para :8043

5. OHIF faz requisições DicomWeb para :8043 (proxy nginx)

6. Nginx recebe a requisição e executa auth_request:
   GET http://backend:8000/api/viewer/token/validate
   Headers: X-Viewer-Token, X-Original-URI

7. Backend (ViewerTokenController@validate):
   → Lê token no Redis
   → Extrai study_instance_uid da URI
   → Verifica se o estudo pertence ao tenant do token
   → Retorna 200 (ok) ou 401/403

8. Nginx repassa ao Orthanc :8042 somente se o backend retornou 200

​

Configuração do OHIF

dataSources: [{
    configuration: {
        wadoUriRoot: 'http://localhost:8043/dicom-web',
        qidoRoot: 'http://localhost:8043/dicom-web',
        wadoRoot: 'http://localhost:8043/dicom-web',
    }
}]

​

13. Frontend — Next.js

​

Estrutura de rotas

frontend/app/
  (auth)/
    login/page.tsx             # Tela de login
  (main)/
    (app)/                     # Usuários comuns e tenant admins
      studies/page.tsx         # Lista de estudos
      studies/[id]/page.tsx    # Detalhe do estudo + laudo + viewers (nova aba / split view) + card histórico
      patients/page.tsx        # Lista de pacientes
      patients/[id]/page.tsx   # Detalhe do paciente
    (tenant-admin)/            # Apenas tenant admins
      tenant/page.tsx          # Painel do tenant
      tenant/templates/...     # Gerenciar templates de laudo
      tenant/report-presets/   # Gerenciar presets
      tenant/settings/         # Configurações (logo, nome)
    (super-admin)/             # Apenas super admins
      admin/tenants/           # Gerenciar clínicas
      admin/units/             # Gerenciar unidades
      admin/users/             # Gerenciar usuários
      admin/modalities/        # Gerenciar aparelhos

​

Autenticação

​

Layout e UX

• Sidebar recolhível: rail verde (w-px bg-primary) na borda direita percorre toda a altura. Botão redondo (22px) no 1/4 superior do rail abre/fecha. Colapsa para modo ícones (w-[48px]) com labels animados. Preferência salva em localStorage. Fecha automaticamente ao entrar em /studies/[id].
• Split view: ao abrir viewer “Junto com Laudo”, o layout troca para h-[calc(100vh-52px)] sem padding — iframe OHIF à esquerda (flex-1) + painel de laudo à direita (w-[460px]).

​

Serviços de API

frontend/lib/api/
  client.ts          # Instância Axios configurada
  studies-service.ts # Estudos, laudos, thumbnail, viewer token; blobToBase64 helper interno
  tenant-service.ts  # Templates, presets, usuários, unidades
  admin-service.ts   # Tenants, unidades, modalidades (super admin)

​

Env vars do frontend

NEXT_PUBLIC_API_BASE_URL=http://localhost:8000/api      # Backend
NEXT_PUBLIC_OHIF_VIEWER_URL=http://localhost:3001        # OHIF viewer

​

14. Proxy CORS do Orthanc

1. /_auth (internal) — repassa para backend:8000/api/viewer/token/validate com os headers necessários. Nunca é acessado diretamente do browser.
2. / — valida token via auth_request /_auth, depois faz proxy para orthanc:8042. Adiciona headers CORS para o browser poder fazer requisições cross-origin.

​

15. Como Editar Cada Parte

​

Adicionar uma nova rota de API

1. Editar backend/routes/api.php — adicionar a rota no grupo correto
2. Criar o método no controller correspondente em backend/app/Http/Controllers/
3. Recarregar: docker exec pacs_backend php artisan octane:reload

​

Adicionar um novo campo ao banco

1. Criar migration: docker exec pacs_backend php artisan make:migration nome_da_migration
2. Editar o arquivo em backend/database/migrations/
3. Rodar: docker exec pacs_backend php artisan migrate
4. Adicionar o campo em $fillable e $casts no Model correspondente

​

Alterar a configuração do Orthanc

1. Editar docker/orthanc/orthanc.json
2. Recriar o container: docker compose up -d --force-recreate orthanc

​

Alterar o hook Lua (webhook)

1. Editar docker/orthanc/scripts/hook.lua.template
2. Recriar: docker compose up -d --force-recreate orthanc

​

Alterar o proxy nginx (CORS / autenticação do viewer)

1. Editar docker/orthanc-cors-proxy/nginx.conf
2. Recarregar: docker compose up -d --force-recreate orthanc-cors-proxy

​

Alterar a configuração do OHIF

1. Editar docker/ohif/app-config.js
2. Recarregar: docker compose up -d --force-recreate ohif

​

Adicionar uma página no frontend

1. Criar frontend/app/(grupo)/caminho/page.tsx
2. O Next.js recarrega automaticamente (hot reload via volume mount)

​

Alterar o worker Python

1. Editar worker/main.py
2. Recriar: docker compose up -d --force-recreate worker

​

Rodar os testes do backend

docker exec pacs_backend php artisan test
# ou localmente dentro de /backend:
composer test

​

Ver logs de um serviço

docker logs pacs_backend -f
docker logs pacs_worker -f
docker logs pacs_orthanc -f

​

16. Arquitetura Alvo — Orthanc On-Premise com Forwarding

Esta seção descreve a arquitetura futura desejada, que ainda não está implementada. O objetivo é que cada clínica tenha um Orthanc local instalado em sua infraestrutura, que encaminha os estudos para o cloud de forma autenticada e identificada.

​

Motivação

1. Latência e dependência de internet — a modalidade precisa de conexão estável para enviar a imagem. Se a internet cair, o exame não chega ao sistema.
2. Identificação frágil — o tenant/unit é descoberto por lookup do AET. Se o AET não estiver cadastrado, o estudo vai para quarentena.
3. Exposição da porta DICOM (4242) na internet — qualquer IP pode tentar enviar DICOMs.

​

Fluxo alvo

[Aparelho DICOM]
      │ C-STORE (rede interna da clínica)
      ▼
[Orthanc Local — on-premise na clínica]
      │ armazena localmente (funciona offline)
      │ forwarding autenticado quando há internet
      ▼
[Cloud — autenticação identifica tenant + unit]
      │
      ▼
[Orthanc Cloud / Backend Laravel]
      │ webhook → processamento normal
      ▼
[Worker Python → PostgreSQL]

​

Opção A — VPN dedicada por clínica/unidade

Orthanc local ──[ túnel VPN ]──▶ Cloud Orthanc :4242

• Isolamento total de rede — o tráfego DICOM nunca passa pela internet aberta
• O IP do túnel pode ser usado como identidade (cada clínica tem um IP de VPN distinto)
• Familiar para equipes de TI de hospitais (VPN site-to-site é padrão na área)
• Protege a porta DICOM — :4242 no cloud só aceita conexões de IPs VPN conhecidos

• Não escala bem — com 100+ clínicas, são 100+ túneis para gerenciar, monitorar, renovar
• Custo operacional alto: cada novo cliente exige provisionamento manual de VPN
• Troubleshooting complexo quando o túnel cai (logs de VPN + logs de DICOM misturados)
• Depende de compatibilidade com o roteador/firewall do cliente

​

Opção B — mTLS (Mutual TLS) sem VPN

Orthanc local
  │ POST https://pacs.cloud.com/dicom-web/studies
  │ TLS client cert: CN=unit_id_abc123
  ▼
Cloud nginx
  │ valida cert (nossa CA)
  │ extrai unit_id do CN
  ▼
Backend Laravel (já sabe tenant + unit sem lookup de AET)

• Escala para milhares de clínicas sem nenhuma configuração de rede extra
• Revogar acesso de uma clínica = revogar o certificado (imediato, sem alterar infra)
• Sem VPN para gerenciar — cada cliente só precisa de internet comum
• Orthanc já suporta nativamente (DicomWeb com HTTPS + certificado de cliente)
• Padrão da indústria para APIs entre serviços em healthcare (SMART on FHIR, IHE)

• Requer infraestrutura de PKI (Certificate Authority própria ou serviço como CFSSL/Vault)
• Certificados precisam ser renovados periodicamente (pode ser automatizado com ACME)
• Configuração inicial do Orthanc local é mais técnica (TLS + cert path)
• O tráfego passa pela internet (mitigado pelo TLS, mas não tem isolamento de rede)

​

Opção C — API Key no cabeçalho HTTP

Orthanc local
  │ POST https://pacs.cloud.com/api/dicom-ingest
  │ Header: X-Tenant-Key: abc123def456
  ▼
Backend Laravel (valida chave na tabela api_keys)

• Implementação mais simples de todas — só um campo na config do Orthanc local
• Fácil de entender e debugar (a chave aparece nos logs)
• Não requer infraestrutura de PKI

• Menos seguro que mTLS — a chave pode vazar (logs, config exposta, etc.)
• Rotacionar chaves exige atualização manual na config do Orthanc de cada clínica
• Sem autenticação no nível de transporte — depende inteiramente do HTTPS para proteção

​

Comparativo das opções

​

Topologia dos Orthancs locais

​

Opção T1 — Um Orthanc por unidade física

Clínica ABC
  ├── Unidade Centro  → Orthanc local (unit_id=AAA) → cloud
  ├── Unidade Norte   → Orthanc local (unit_id=BBB) → cloud
  └── Unidade Sul     → Orthanc local (unit_id=CCC) → cloud

• A identidade de unidade está na config da máquina — sem ambiguidade
• Falha em uma unidade não afeta as outras
• Cada Orthanc é mais simples (menos estudos, menos carga)
• Padrão da indústria (cada site tem seu nó PACS próprio)

• Mais máquinas para instalar, atualizar e monitorar
• Custo de hardware multiplicado pelo número de unidades

​

Opção T2 — Um Orthanc por clínica, unidade identificada pelo AET

Clínica ABC
  └── Orthanc local (tenant_id=ABC)
        ├── Aparelho Unidade Centro (AET=CENTRO_RX01) → unit=AAA
        ├── Aparelho Unidade Norte  (AET=NORTE_TC01)  → unit=BBB
        └── Aparelho Unidade Sul    (AET=SUL_RM01)    → unit=CCC

• Uma instalação por cliente — mais simples de gerenciar
• Aparelhos continuam usando AET como identificador (zero mudança nas modalidades)

• Se o Orthanc local cair, todas as unidades param
• Ponto único de falha por clínica
• A rede interna precisa alcançar aparelhos de unidades diferentes (pode exigir configuração de rede)

​

Opção T3 — Um Orthanc por clínica com roteamento interno por AET

​

Recomendação de caminho (análise inicial)

1. Autenticação: começar com API Key (simples de onboarding) e migrar para mTLS quando a base de clientes exigir mais segurança ou compliance.
2. Topologia: Um Orthanc por unidade física — é o padrão da indústria, elimina o ponto único de falha, e simplifica a identificação (a identidade já está na config da máquina).
3. VPN: reservar para clientes enterprise que exijam por contrato — não usar como padrão do produto.

​

Decisão adotada — VPN por clínica/unidade

• A grande maioria dos aparelhos de imagem médica (CT, RX, RM) usa DICOM C-STORE sobre a porta 4242 — um protocolo binário que não é HTTP.
• As opções API Key e mTLS dependem de DicomWeb (STOW-RS), que é DICOM sobre HTTP/HTTPS. Só equipamentos modernos suportam isso; equipamentos legados (a maioria nas clínicas brasileiras) não suportam.
• Expor a porta 4242 na internet pública sem VPN significa que qualquer IP pode tentar enviar imagens — inaceitável para um sistema de saúde.
• O Caddy (proxy reverso) não consegue fazer proxy de DICOM — o protocolo é binário, não HTTP, então não há como proteger a porta 4242 com TLS via Caddy.

• Mantém a porta 4242 completamente fora da internet pública.
• Os aparelhos continuam usando DICOM C-STORE nativo, sem nenhuma mudança de configuração no equipamento.
• O tráfego de imagens médicas (dados sensíveis) nunca trafega pela internet aberta.
• A identidade da clínica/unidade é garantida pelo IP do túnel VPN (cada clínica tem um IP de VPN fixo e distinto).

[Aparelho DICOM — CT, RX, RM, etc.]
      │ C-STORE (rede interna da clínica, protocolo nativo)
      ▼
[Orthanc Local — on-premise na unidade]
      │ armazena localmente (funciona offline se internet cair)
      │ forwarding via C-STORE ou DicomWeb dentro do túnel VPN
      ▼
[Túnel VPN (WireGuard) — IP fixo por clínica/unidade]
      │
      ▼
[Cloud Orthanc :4242 — só aceita conexões de IPs VPN cadastrados]
      │ webhook → processamento normal
      ▼
[Worker Python → PostgreSQL]

​

Plano de Implementação

​

O que NÃO muda no código

​

Mudanças de código necessárias

1. Firewall — porta 4242 só aceita IPs do range VPN (ufw)
2. Orthanc — KnownAETsOnly: true + DicomModalities com AETs autorizados
3. Job — AET deve estar em modalities com tenant+unit; caso contrário → quarentena

​

Mudanças de infraestrutura

# /etc/wireguard/wg0.conf (servidor cloud)
[Interface]
PrivateKey = <server-private-key>
Address = 10.100.0.1/24
ListenPort = 51820

# Uma seção [Peer] por unidade de clínica:
[Peer]
# Clinica ABC — Unidade Centro
PublicKey = <clinic-public-key>
AllowedIPs = 10.100.0.2/32

[Peer]
# Clinica ABC — Unidade Norte
PublicKey = <clinic2-public-key>
AllowedIPs = 10.100.0.3/32

# Bloquear acesso público à porta DICOM
ufw deny 4242
# Permitir apenas do range VPN
ufw allow from 10.100.0.0/24 to any port 4242

// orthanc.json do Orthanc local
{
  "DicomAet": "CLINICA_A_U1",  // AET cadastrado no nosso painel
  "OrthancPeers": {
    "cloud": {
      "Url": "http://10.100.0.1:8042",  // Orthanc cloud via VPN
      "Username": "",
      "Password": ""
    }
  }
}

function OnStableStudy(studyId, tags, metadata)
    SendToPeer("cloud", studyId)
end

​

Processo de onboarding de nova unidade

1. Provisionar par de chaves WireGuard para a unidade
2. Adicionar [Peer] no wg0.conf do servidor com o IP fixo atribuído (ex: 10.100.0.5)
3. Instalar WireGuard client + Orthanc local na VM da clínica
4. Configurar o Orthanc local com o AET da unidade e forwarding para o cloud via VPN
5. No painel do sistema: cadastrar a unidade em modalities com o AET e o vpn_ip atribuído
6. Fazer um envio de teste e verificar os logs do pacs_queue

​

Estado de implementação