Skip to content

Relatório Tecnológico: Monitor SEFAZ

1. Introdução

Este relatório tem como objetivo detalhar a arquitetura e o stack tecnológico das aplicações monitor-sefaz-api (Backend) e monitor-sefaz-front (Frontend), que compõem o sistema Monitor SEFAZ. A análise foi realizada com base na inspeção do código-fonte e na observação da funcionalidade do site monitorsefaz.com.br.

2. Stack Tecnológico

O sistema adota uma arquitetura moderna de Single Page Application (SPA) com um backend robusto, utilizando tecnologias de ponta para garantir desempenho, escalabilidade e manutenibilidade.

Componente Tecnologia Principal Frameworks/Bibliotecas Chave Propósito
Frontend React (com TypeScript) Vite, TailwindCSS, shadcn/ui, recharts, wouter, i18next Interface do usuário, visualização de dados em tempo real.
Backend .NET 9.0 (C#) ASP.NET Core, Minimal APIs, JWT Bearer, StackExchange.Redis, AWS SDKs, Serilog Lógica de negócios, comunicação com SEFAZ, autenticação, caching.
Monitoramento SEFAZ C# (.NET 9.0) HttpClient, SOAP XML Integração e consulta aos serviços de Nota Fiscal Eletrônica (NFe), Conhecimento de Transporte Eletrônico (CTe) e Documento de Conhecimento Eletrônico (DCe).

3. Arquitetura do Sistema

A arquitetura segue os princípios da Clean Architecture (Arquitetura Limpa), com o backend estruturado em camadas para isolar a lógica de domínio e facilitar testes e manutenção.

3.1. Diagrama de Arquitetura (Mermaid)

O fluxo de dados e a interação entre os principais componentes do sistema podem ser visualizados no diagrama abaixo:

graph TD
A[Usuário Browser] -->|HTTPS| B[Frontend React]
B -->|REST API| C[Backend .NET 9.0]
C -->|Consulta Status| D[SefazMonitor.Sefaz]
D -->|HttpClient SOAP| E[Serviços SEFAZ]
C -->|Cache| F[Redis]
C -->|Auth| G[AWS Cognito]
C -->|Logs| H[CloudWatch]

3.2. Fluxo de Consulta de Status SEFAZ (Mermaid)

O serviço de monitoramento no backend (SefazStatusService) implementa uma lógica sofisticada para garantir a performance e a resiliência das consultas, incluindo mecanismos de caching e contingência.

flowchart TD
A[Requisição de Status] --> B{UF e Serviço Válidos?}
B -->|Não| C[Erro Inválido]
B -->|Sim| D[Verificar Cache Redis]
D -->|Cache Válido| E[Retornar do Cache]
D -->|Cache Inválido| F[Chamar SOAP SEFAZ]
F --> G{Status Retornado?}
G -->|Sim| H[Salvar no Cache]
H --> I[Retornar Status SEFAZ]
G -->|Não| J{Tentar Contingência?}
J -->|Sim| K[Serviço Contingência]
K --> I
J -->|Não| L[Status Indisponível]

4. Componentes Chave do Backend

O projeto monitor-sefaz-api é o coração da aplicação, responsável por toda a lógica de monitoramento e integração.

4.1. Estrutura em Camadas

O backend é organizado em camadas seguindo Clean Architecture:

  • SefazMonitor.Api (Presentation): Minimal APIs, Middlewares, Extensions
  • SefazMonitor.Application (Use Cases): Casos de uso e orquestração de negócio
  • SefazMonitor.Domain (Core): Entidades, Value Objects, Interfaces
  • SefazMonitor.Infrastructure (External): Repositórios Redis, Serviços externos, Background Services
  • SefazMonitor.Sefaz (Domain Specific): Serviços SOAP específicos para SEFAZ

4.2. Módulo de Monitoramento (SefazMonitor.Sefaz)

Este módulo é o responsável direto pela comunicação com os serviços da SEFAZ.

  • Serviços SOAP:
  • NfeStatusServicoSoapService: Consulta status de NFe
  • NfceStatusServicoSoapService: Consulta status de NFCe
  • CteStatusServicoSoapService: Consulta status de CTe

  • DceStatusServicoSoapService: Consulta status de DCe

  • Serviço Principal:

  • SefazStatusService: Orquestra as consultas aos serviços SOAP

  • Integração: Utiliza HttpClient diretamente para comunicação SOAP com os servidores da SEFAZ, construindo requisições XML manualmente conforme os protocolos específicos de cada serviço.

  • Configuração: Possui opções de configuração (SefazOptions) para definir o ambiente (Homologação/Produção), timeout, e regras de caching e contingência.

  • Certificados: CertificateService gerencia certificados digitais A1/A3 para autenticação nas requisições SOAP.

4.3. Persistência e Caching

  • Redis (StackExchange.Redis): Utilizado para caching e persistência de resultados de consultas à SEFAZ. Isso é crucial para reduzir a latência e a carga sobre os serviços externos, além de otimizar a performance da aplicação.

  • Estruturas de Dados Redis:

  • Strings: Status mais recente
  • Sorted Sets: Histórico ordenado por timestamp
  • TTL: Expiração automática de dados (2h para latest, 24h para histórico)

4.4. Segurança e Autenticação

  • Autenticação: O uso de Microsoft.AspNetCore.Authentication.JwtBearer indica que a API utiliza JSON Web Tokens (JWT) para proteger seus endpoints.

  • Usuários: A presença de AWSSDK.CognitoIdentityProvider e Otp.NET indica que a autenticação de usuários é gerenciada via AWS Cognito, com suporte a autenticação de dois fatores (2FA/OTP).

  • Data Protection: Microsoft.AspNetCore.DataProtection é utilizado para criptografia de dados sensíveis, com chaves persistidas em filesystem.

4.5. Background Services

  • MonitorWorker: Serviço em background que executa monitoramento contínuo das SEFAZs a cada 30 segundos
  • SefazErrorsSeeder: Semeia erros SEFAZ catalogados no Redis
  • AdminUserSeeder: Semeia usuário administrador inicial
  • FeaturesSeeder: Semeia features do roadmap
  • RedisIndexSeeder: Cria índices necessários no Redis

4.6. Observabilidade

  • Logging: A integração com Serilog e AWSSDK.CloudWatchLogs demonstra um sistema de observabilidade maduro, onde os logs da aplicação são centralizados no AWS CloudWatch, facilitando o monitoramento e a depuração em ambiente de produção.

  • Health Checks: Endpoints de health check (/health/live, /health/ready) para monitoramento de infraestrutura.

4.7. Bibliotecas e Dependências Principais

Backend (.NET 9.0): - Microsoft.AspNetCore.*: Framework web ASP.NET Core - StackExchange.Redis: Cliente Redis - AWSSDK.CognitoIdentityProvider: Integração AWS Cognito - AWSSDK.CloudWatchLogs: Logs no CloudWatch - Serilog.AspNetCore: Framework de logging estruturado - Serilog.Sinks.AwsCloudWatch: Sink para CloudWatch - Otp.NET: Autenticação de dois fatores - System.IdentityModel.Tokens.Jwt: Tokens JWT - Google.Apis.Auth: Autenticação Google OAuth - Swashbuckle.AspNetCore: Swagger/OpenAPI - Slack.Webhooks: Notificações via Slack (opcional) - Microsoft.Extensions.Http: HttpClient factory

5. Componentes Chave do Frontend

O projeto monitor-sefaz-front oferece uma experiência de usuário moderna e responsiva.

  • Interface: Construída com React e TypeScript, garantindo tipagem forte e um desenvolvimento escalável.
  • Estilização: Utiliza TailwindCSS para um desenvolvimento rápido e modular de estilos, complementado pela biblioteca de componentes shadcn/ui.
  • Visualização de Dados: O uso de recharts é fundamental para a exibição dos gráficos de tempo de resposta e histórico de status, conforme observado no site.
  • Roteamento: wouter é utilizado para roteamento no frontend.
  • Internacionalização: A presença de i18next indica que a aplicação está preparada para suportar múltiplos idiomas.
  • Build: Vite é utilizado como ferramenta de build, oferecendo desenvolvimento rápido e builds otimizados.

6. Tecnologias de Infraestrutura

6.1. Containerização

  • Docker: Aplicação containerizada para facilitar deploy e consistência entre ambientes
  • Docker Compose: Orquestração local para desenvolvimento
  • Multi-stage builds: Otimização de imagens Docker

6.2. Cloud e Deploy

  • AWS: Utilização de serviços AWS para produção
  • AWS Cognito: Autenticação de usuários
  • AWS CloudWatch: Logs e monitoramento
  • AWS ECS/Fargate: Deploy containerizado (inferido)
  • Redis: Cache e persistência (pode ser Redis Cloud ou self-hosted)

6.3. CI/CD

  • GitHub Actions: Pipeline de CI/CD (conforme .github/workflows/deploy.yml)

7. Decisões Técnicas Importantes

7.1. Comunicação SOAP com SEFAZ

O sistema utiliza HttpClient diretamente para comunicação SOAP, construindo requisições XML manualmente conforme os protocolos específicos de cada serviço SEFAZ. Esta abordagem oferece:

  • Controle total: Implementação direta sem dependências de bibliotecas externas
  • Manutenibilidade: Código específico para as necessidades do projeto
  • Performance: Menor overhead comparado a bibliotecas genéricas
  • Transparência: Visibilidade completa sobre as requisições e respostas

7.2. Clean Architecture

A escolha por Clean Architecture proporciona:

  • Testabilidade: Fácil mockar dependências
  • Manutenibilidade: Mudanças isoladas por camada
  • Flexibilidade: Trocar implementações sem afetar domínio
  • Onboarding: Estrutura clara para novos desenvolvedores

7.3. Minimal APIs

O uso de Minimal APIs ao invés de Controllers tradicionais oferece:

  • Menos boilerplate: Código mais enxuto
  • Performance: Menor overhead
  • Modernidade: Padrão atual do .NET
  • Type Safety: Melhor inferência de tipos

7.4. Redis como Persistência Principal

A escolha por Redis oferece:

  • Performance: Latência sub-milissegundo
  • Estruturas de Dados: Sorted Sets perfeitos para histórico temporal
  • Simplicidade: Não requer schema migrations
  • TTL Nativo: Expiração automática de dados

8. Conclusão

O Monitor SEFAZ é construído sobre uma base tecnológica sólida e moderna, combinando a robustez do stack .NET 9.0 no backend com a agilidade e reatividade do React no frontend. A arquitetura é bem definida, seguindo Clean Architecture, com foco em performance (caching com Redis), segurança (JWT, Cognito, OTP, Data Protection) e resiliência (lógica de contingência e observabilidade com CloudWatch).

A implementação direta de comunicação SOAP com SEFAZ usando HttpClient demonstra controle técnico e flexibilidade, permitindo adaptações específicas às necessidades do projeto sem depender de bibliotecas comerciais externas. O uso de tecnologias modernas como Minimal APIs, Background Services e structured logging garante uma base sólida para evolução contínua do sistema.

Última Atualização: 26 de Dezembro de 2025
Versão do Documento: 2.0
Mantido por: Equipe de Desenvolvimento Monitor SEFAZ