NexarGrid Documentation

# 1. Visão Geral Arquitetural

O NexarGrid adota uma Arquitetura de Microsserviços Orientada a Eventos (Event-Driven Microservices Architecture), projetada para alta disponibilidade, escalabilidade elástica e consistência eventual. O sistema é construído sobre o framework MoleculerJS (Node.js), utilizando NATS como backbone de mensageria e SurrealDB como persistência poliglota.

# Princípios Fundamentais

Desacoplamento: Serviços comunicam-se exclusivamente via mensagens (RPC ou Pub/Sub), sem dependências diretas de código.
Imutabilidade: O estado crítico (escalas) é gerido via Event Sourcing, onde a verdade é a sequência de eventos, não apenas o estado atual.
Resiliência: Design Fail-Fast com Circuit Breakers e Bulkheads para isolar falhas em serviços individuais.

# 2. Diagrama de Topologia (C4 Nível 2 - Container)

Este diagrama ilustra os containers de execução e as fronteiras de comunicação do sistema.


Gerando diagrama...

# 3. Padrões de Arquitetura

# 3.1 Event Sourcing & CQRS

Para o domínio de escalas (ShiftPack), não armazenamos apenas o estado final. Cada alteração é um evento imutável.

Command Side (Escrita): Recebe intenções do usuário (ex: AssignDoctor). Valida regras de negócio e, se aprovado, persiste um evento DoctorAssigned.
Query Side (Leitura): Projections consomem esses eventos para atualizar visualizações otimizadas no Redis ou tabelas de leitura no SurrealDB, permitindo consultas ultra-rápidas sem onerar o modelo de escrita.

Fluxo de Exemplo:

Comando: POST /shifts/123/assign { doctorId: 456 }
Validação: Verifica qualificações e colisões.
Evento: ShiftAssigned { shiftId: 123, doctorId: 456, timestamp: ... } persistido.
Projeção: Atualiza o documento JSON da escala e invalida o cache da API de visualização.

# 3.2 Saga Pattern (Transações Distribuídas)

Operações que abrangem múltiplos serviços (ex: Publicar Escala + Gerar Previsão Financeira + Notificar Médicos) são orquestradas via Sagas Coreografadas.

Se o serviço de Pagamento falhar ao calcular a previsão, um evento de compensação PaymentCalculationFailed é emitido.
O serviço de Escala escuta esse evento e reverte o status da escala de “Publicada” para “Rascunho”, garantindo consistência eventual.

# 4. Segurança e Autenticação

# 4.1 Fluxo de Identidade

Utilizamos JWT (JSON Web Tokens) assinados com RS256 para autenticação stateless.


Gerando diagrama...

# 4.2 Controle de Acesso (RBAC)

As permissões são granulares e baseadas em Scopes.

Roles: Admin, Manager, Coordinator, Provider.
Scopes: shift:read, shift:write, financial:view.
O Gateway (Traefik + Middleware) rejeita requisições que não possuam os escopos necessários antes mesmo de chegarem aos serviços.

# 5. Estratégia de Escalabilidade

# 5.1 Horizontal Scaling

O framework Moleculer permite iniciar múltiplas réplicas de qualquer serviço. O registro e descoberta são automáticos via NATS. Se o serviço CollisionDetector estiver sob alta carga, novas instâncias podem ser subidas instantaneamente, e o tráfego será distribuído automaticamente.

# 5.2 Database Sharding (Futuro)

O SurrealDB suporta distribuição nativa. Planejamos implementar sharding baseado no tenant_id (Unidade Hospitalar), garantindo que dados de grandes hospitais sejam processados em nós dedicados do cluster de banco de dados.

# 6. Observabilidade

A saúde do sistema é monitorada em três pilares:

Logs Estruturados: Todos os serviços emitem logs em formato JSON (Pino logger) agregados no ElasticSearch/Loki.
Métricas (Prometheus): Exposição de métricas de runtime (CPU, RAM, Event Loop Lag) e de negócio (Shifts Created/min, Payment Errors).
Tracing Distribuído (Jaeger): Cada requisição recebe um Request-ID único que propaga por toda a cadeia de chamadas, permitindo visualizar gargalos de latência em visualizações de Waterfall.

# 7. Modelagem de Domínio (Domain Hierarchy)

A estrutura de dados do NexarGrid reflete a complexidade organizacional de grandes redes hospitalares. A hierarquia foi desenhada para suportar múltiplas unidades, regras de negócio específicas e ciclos de escala rotativos.

# 7.1 Diagrama de Classes do Domínio


Gerando diagrama...

# 7.2 Anatomia da Escala (ShiftPack & Slots)

O conceito de ShiftPack é central para a gestão de escalas. Ele não representa apenas um dia, mas um padrão de recorrência.

ShiftPack (Pacote): Agrupa todos os plantões de um dia específico da semana (ex: “Segunda-feira”) ou de uma regra de rotação.
Slots (Horários): Divisões temporais dentro do pacote (ex: Plantão Diurno 07:00-19:00, Plantão Noturno 19:00-07:00).
Rotation (Rotação): Lógica que define qual profissional assume o slot em cada semana do ciclo (Week 1, Week 2, Week 3, Week 4).

Exemplo Visual de Rotação:

Se o Dr. A trabalha na Semana 1 e 3, e o Dr. B na Semana 2 e 4, o ShiftPack gerencia essa alternância automaticamente ao gerar a escala mensal, criando os ShiftItems correspondentes para cada data específica.

Arquitetura de Sistema