Decisões arquiteturais

Registro das decisões tomadas na reconstrução deste sistema, incluindo os pontos em que a implementação se afasta deliberadamente da lista de tecnologias sugerida na especificação original (seção 6). Cada decisão inclui o motivo e o que reconsiderar se as premissas mudarem.

1. Next.js full-stack, não backend Node.js separado + frontend React Native

Decisão: um único app Next.js 16 (App Router) serve tanto a API quanto a interface web, acessada via navegador (responsiva, funciona bem em celular) em vez de um app nativo React Native.

Por quê: o sistema não precisa de recursos exclusivos de app nativo (câmera, Bluetooth, background tasks pesadas). Um único deploy, um único runtime, menos superfície de configuração — mais simples de operar para a TI do hospital, dado que o requisito real é "acessível via celular", não "app instalável". A perda é notificação push mais limitada no iOS (ver decisão 5) e nenhuma distribuição via loja de apps.

Reconsiderar se: o hospital exigir presença nas lojas de app, uso offline robusto, ou integração com hardware do celular (câmera para outra finalidade, Bluetooth direto) que só um app nativo resolve bem.

2. PostgreSQL único, não PostgreSQL + MongoDB

Decisão: um único banco PostgreSQL. A tabela EventoAuditoria (com coluna payload JSONB para dados semi-estruturados) cobre o papel de "log de eventos em tempo real" que a especificação original cogitava para o MongoDB.

Por quê: volume de chamados de um hospital (mesmo grande) é ordens de grandeza menor do que os cenários em que um segundo banco NoSQL para "logs/eventos" se paga em complexidade operacional. Dois bancos = duas estratégias de backup, duas superfícies de falha, duas tecnologias para a equipe de TI manter. PostgreSQL sozinho, com os índices em Chamado (criadoEm, [tipo, status, criadoEm]) e em EventoAuditoria (criadoEm), atende as consultas de relatório sem problema nesse volume.

Reconsiderar se: o volume de eventos crescer por ordens de grandeza (múltiplos hospitais, telemetria de alta frequência de muitos dispositivos IoT) a ponto de as consultas de relatório ficarem lentas — aí uma tabela de agregados diários materializada resolveria antes de precisar de um segundo banco.

3. Socket.IO (WebSocket), não MQTT

Decisão: tempo real entre servidor e dashboards/dispositivos usa Socket.IO sobre WebSocket (com fallback automático), não um broker MQTT dedicado.

Por quê: os "clientes" deste sistema são navegadores (dashboards) e um único endpoint HTTP para o botão de emergência (POST /api/chamados/emergencia) — não uma frota de sensores IoT publicando em alta frequência, que é o caso de uso onde MQTT brilha (pub/sub leve, QoS configurável, ideal para redes instáveis de muitos dispositivos batery-powered). Socket.IO integra nativamente com autenticação por sessão (JWT do Auth.js) e não exige operar um broker adicional.

Reconsiderar se: o número de dispositivos IoT crescer para dezenas por quarto/hospital com necessidade de QoS/offline queuing do lado do broker — nesse ponto, migrar só a ingestão dos dispositivos (não os dashboards) para MQTT seria razoável, mantendo Socket.IO para a UI.

4. Sem Grafana/Metabase — relatórios in-app

Decisão: a tela /dashboard/supervisor/relatorios (números por setor, gráfico, tabela de pendentes) é construída no próprio Next.js com Recharts, consultando src/lib/relatorios/queries.ts diretamente — não há Grafana/Metabase implantado.

Por quê: os requisitos da especificação (chamados por setor, tempo médio de resposta, pendentes, SLA) são atendidos por algumas queries bem definidas; implantar e manter uma ferramenta de BI adicional (com seu próprio banco de conexão, autenticação, deploy) não se justifica só para isso.

Reconsiderar se: o hospital quiser dashboards ad-hoc para usuários não-técnicos montarem seus próprios relatórios, ou cruzar dados deste sistema com outros sistemas hospitalares — aí Metabase (mais simples de operar que Grafana para esse perfil de usuário) conectado ao mesmo Postgres seria o próximo passo natural, sem precisar mudar o schema.

5. Web Push, não notificação push nativa

Decisão: notificações push usam Web Push padrão (VAPID) via service worker (public/sw.js), consequência direta da decisão 1 (sem app nativo).

Por quê: é a opção que existe para apps web. Funciona nativamente em Android/desktop (Chrome, Edge, Firefox). No iOS Safari, só funciona se o usuário instalar o site como PWA ("Adicionar à Tela de Início") — uma limitação da Apple, não deste projeto, e algo a comunicar explicitamente para a equipe no treinamento (plano-de-treinamento.md).

Reconsiderar se: a experiência de push no iOS sem instalação de PWA for um requisito não-negociável — nesse caso, um app nativo (ou wrapper tipo Capacitor) seria necessário só para push, o que reabriria a decisão 1.

6. Sem Kubernetes — Docker Compose + proxy reverso

Decisão: deploy via Docker Compose (Postgres + app + Caddy para HTTPS automático), não Kubernetes.

Por quê: a escala real (chamados de um ou poucos hospitais da rede Unimed NF) não demanda orquestração de containers com autoscaling horizontal. Compose é suficiente para alta disponibilidade básica (restart automático de containers) e é muito mais simples de operar para uma equipe de TI hospitalar sem um time de plataforma dedicado.

Reconsiderar se: o sistema for adotado por múltiplas unidades simultaneamente com necessidade real de autoscaling, deploy multi-região, ou já existir um cluster Kubernetes na Unimed NF que a TI prefira reaproveitar — nesse caso, a containerização já feita (Dockerfile) facilita a migração; não seria um recomeço do zero.

7. Auth.js v5 (beta), não uma solução própria de sessão

Decisão: autenticação por usuário/senha via Auth.js v5 (next-auth@5.0.0-beta.32), sessão JWT.

Por quê: apesar de a versão 5 ainda estar em beta no momento desta reconstrução, é a integração padrão e mais testada para App Router do Next.js, com suporte a middleware de borda e route handlers. A alternativa de rolar autenticação própria (JWT manual + cookies) tem mais superfície de erro em um sistema hospitalar do que depender de uma biblioteca com grande adoção, mesmo em beta prolongado.

Ação de acompanhamento: monitorar o lançamento de uma versão estável (GA) do Auth.js v5 e atualizar assim que disponível — não é uma decisão definitiva, é a melhor opção pragmática hoje. Rodar npm audit periodicamente enquanto isso (ver CI, .github/workflows/ci.yml).

8. WebRTC só com STUN, sem servidor TURN

Decisão: o áudio bidirecional paciente-posto (/chamar/[numeroQuarto] ↔ tela de atendimento da Enfermagem) usa WebRTC com um único servidor STUN público (stun:stun.l.google.com:19302) pra descoberta de IP — sem servidor TURN (retransmissão) próprio.

Por quê: STUN sozinho resolve a maioria das conexões dentro da mesma rede Wi-Fi do hospital (o cenário mais comum: paciente e posto de enfermagem na mesma rede local) sem nenhuma infraestrutura adicional pra manter. Um TURN é outro serviço rodando 24/7, com seu próprio custo de banda (todo o áudio passa por ele quando é necessário) — não se justifica sem antes confirmar que falhas de conexão direta são um problema real em produção.

O que quebra sem TURN: chamadas entre redes com NAT simétrico ou firewall corporativo agressivo (comum em redes hospitalares segmentadas/VLANs isoladas) podem não conseguir estabelecer conexão direta. Sinalização (quem liga pra quem) sempre funciona — é só a conexão de mídia P2P que pode falhar nesses casos.

Reconsiderar se: usuários relatarem chamadas que tocam mas não conectam — sintoma clássico de STUN insuficiente. Solução: subir um TURN próprio (ex.: coturn, mesmo docker-compose) ou usar um serviço gerenciado (Twilio STUN/TURN, Cloudflare Calls). É uma mudança só de configuração no array ICE_SERVERS (src/hooks/useChamadaAudioPaciente.ts e src/hooks/useChamadaAudioStaff.ts), não de arquitetura de sinalização.