Backoffice N3 - Plataforma de Integração e Processamento de Transações

Solução completa para integração entre Concessionárias de Rodovias, Operadoras de Serviços de Arrecadação (OSA) e Sistema de Pedágio Eletrônico

Versão 1.0 | 2025

Sumário

Resumo Executivo

Visão Executiva

O Backoffice N3 é uma plataforma backoffice de integração que conecta concessionárias de pedágio com Operadoras de Serviços de Arrecadação (OSAs) e o Portal Pedágio Eletrônico, garantindo conformidade com o protocolo ARTESP 001/14 e processamento em tempo real de transações de pedágio. Suporta tanto sistemas free flow (sem cancelas, com identificação automática em velocidade) quanto praças tradicionais com leitura de tags RFID.

Principais Diferenciais

Indicadores de Negócio

Métrica Valor Impacto
Tempo de Processamento < 2 segundos Conformidade SLA ARTESP (24h)
Disponibilidade 99.9% Continuidade operacional garantida
OSAs Suportadas 5 simultâneas Cobertura total do mercado
Auditoria 100% transações Compliance e rastreabilidade
Recovery Automático AVI 5 dias Redução de inadimplência

Visão Geral do Produto

O Desafio

Concessionárias de pedágio enfrentam complexidades significativas na integração com múltiplas Operadoras de Serviços de Arrecadação (OSAs). Cada operadora possui especificações técnicas próprias, protocolos de comunicação distintos e SLAs rigorosos definidos pela ARTESP. A gestão manual dessas integrações resulta em:

  • Alto custo operacional de desenvolvimento e manutenção
  • Risco de não conformidade regulatória (ARTESP 001/14)
  • Dificuldade em escalar para novas operadoras
  • Falta de visibilidade sobre transações em tempo real
  • Complexidade no monitoramento e auditoria
  • Perda de receita por falhas de comunicação

A Solução Backoffice N3

O Backoffice N3 é uma plataforma completa que abstrai toda a complexidade de integração entre concessionárias de pedágio, OSAs e Portal Pedágio Eletrônico. Suporta tanto sistemas free flow quanto praças tradicionais com leitura RFID, oferecendo:

Integração Unificada

Interface única para comunicação com 5 OSAs simultâneas, com conversão automática de protocolos (JSON para Protocol Buffers ARTESP).

Processamento Inteligente

Validação, enriquecimento e cálculo automático de tarifas por categoria veicular, cálculo de DUF (Desconto do Usuário Frequente), monitoramento AVI e recuperação de inadimplentes.

Dashboard Gerencial

Interface web moderna com visualização de métricas, gestão de transações e relatórios exportáveis.

Conformidade Garantida

Implementação completa do protocolo ARTESP 001/14 com auditoria e rastreabilidade de todas as transações.

Casos de Uso

  1. Processamento de Passagens: Captura, validação e distribuição de transações de pedágio para OSAs em tempo real
  2. Gestão de Tags: Sincronização de tags veiculares com múltiplas operadoras
  3. Envio de Evidências: Distribuição automatizada de imagens de passagens para validação
  4. Monitoramento AVI: Acompanhamento automático de passagens pendentes com recuperação programada
  5. Relatórios e Analytics: Exportação de dados operacionais e financeiros em múltiplos formatos
  6. Auditoria Regulatória: Rastreamento completo de comunicações para conformidade ARTESP

Arquitetura da Solução

Visão de Alto Nível

O Backoffice N3 adota uma arquitetura de microserviços baseada em eventos, separando responsabilidades entre camadas de apresentação, processamento e integração.

graph TB subgraph "Camada de Apresentação" Portal[Dashboard Portal
React + Vite] BFF[Dashboard BFF
NestJS] end subgraph "Camada de Processamento Core" Processador[Processador Passagens LST
Spring Boot + Kafka] Relatorios[Relatórios API
NestJS + Prisma] ImageSender[Image Sender Service
Spring Boot CronJob] end subgraph "Camada de Integração" MensageriaProxy[Mensageria ARTESP Proxy
Spring Boot + Protobuf] Bridge[Bridge
Spring Boot JMS] end subgraph "Operadoras (OSAs)" OSA1[Sem Parar] OSA2[ConectCar] OSA3[Veloe] OSA4[Movemais] OSA5[GreenPass] end subgraph "Fontes de Dados" Kafka[(Kafka
Fiscaltech N1/N2)] PostgreSQL[(PostgreSQL)] Redis[(Redis Cache)] end Portal -->|HTTP/REST + JWT| BFF BFF -->|HTTP/REST| Relatorios Kafka -->|JSON| Processador Processador -->|Persistência| PostgreSQL Processador -->|Cache| Redis Kafka -->|JSON| MensageriaProxy MensageriaProxy -->|Protobuf| Bridge ImageSender -->|Query| PostgreSQL ImageSender -->|RabbitMQ| MensageriaProxy Bridge -->|RabbitMQ/JMS| OSA1 Bridge -->|RabbitMQ/JMS| OSA2 Bridge -->|RabbitMQ/JMS| OSA3 Bridge -->|RabbitMQ/JMS| OSA4 Bridge -->|RabbitMQ/JMS| OSA5 style Portal fill:#8b5cf6,color:#fff style BFF fill:#8b5cf6,color:#fff style Processador fill:#059669,color:#fff style Relatorios fill:#059669,color:#fff style ImageSender fill:#059669,color:#fff style MensageriaProxy fill:#f59e0b,color:#fff style Bridge fill:#f59e0b,color:#fff

Princípios Arquiteturais

Separação de Responsabilidades

Cada microserviço possui uma responsabilidade única e bem definida, facilitando manutenção e evolução independente.

Event-Driven Architecture

Comunicação assíncrona via mensageria (Kafka, RabbitMQ) garante desacoplamento e alta disponibilidade.

Clean Architecture

Serviços críticos seguem Clean Architecture com separação clara entre domínio, aplicação e infraestrutura.

API Gateway Pattern

BFF atua como agregador e transformador de dados, otimizando comunicação frontend-backend.

Fluxo de Dados Principal

sequenceDiagram participant N1 as Sistema Pórtico
(N1/N2) participant Kafka as Apache Kafka participant Proc as Processador
Passagens LST participant DB as PostgreSQL participant Proxy as Mensageria
ARTESP Proxy participant RMQ as RabbitMQ participant OSA as OSAs N1->>Kafka: Publicar transação (JSON) Kafka->>Proc: Consumir transação Proc->>Proc: Validar JSON Schema Proc->>Proc: Calcular tarifa Proc->>DB: Persistir transação Proc->>RMQ: Publicar resultado Kafka->>Proxy: Consumir transação Proxy->>Proxy: Converter JSON → Protobuf Proxy->>RMQ: Publicar por OSA RMQ->>OSA: Enviar passagem (Protobuf ARTESP) OSA-->>RMQ: Retornar validação

Componentes do Sistema

Serviços Core do Backoffice N3

1. Dashboard Portal

Frontend Core

Tecnologia: React 19, Vite, TypeScript, TailwindCSS, Radix UI

Responsabilidades:

  • Interface web responsiva para gestão da concessionária
  • Dashboards de métricas (tráfego, receita, transações)
  • Gerenciamento de usuários, veículos e notificações
  • Exportação de relatórios via AWS S3 presigned URLs
  • Autenticação JWT com refresh token

Recursos: State management com Zustand, validação com Zod, internacionalização, tema customizável, proteção bot com Cloudflare Turnstile

2. Dashboard BFF (Backend For Frontend)

Backend Core

Tecnologia: NestJS 11, TypeScript, Node.js, Passport JWT

Responsabilidades:

  • Camada de agregação entre frontend e APIs backend
  • Autenticação e autorização centralizada (JWT)
  • Transformação de dados para formato otimizado do frontend
  • Cache de requisições com node-cache
  • Rate limiting e throttling
  • Proxy reverso para APIs downstream

Recursos: Documentação Swagger, helmet para segurança, Winston logging, suporte a mocks para desenvolvimento

3. Processador Passagens LST

Backend Core

Tecnologia: Java 17, Spring Boot 3.5, Kafka, RabbitMQ, PostgreSQL, Redis

Responsabilidades:

  • Processamento em tempo real de transações de passagem via Kafka (free flow e praças tradicionais RFID)
  • Validação com JSON Schema e enriquecimento de dados
  • Cálculo automático de tarifas por categoria veicular e aplicação de DUF (Desconto do Usuário Frequente)
  • Monitoramento AVI com timeout de 5 dias
  • Recuperação automática de inadimplentes
  • Persistência transacional em PostgreSQL
  • Cache Redis com timeout de 2 segundos

Recursos: Batch processing (500 records), MapStruct para conversão de objetos, Testcontainers para testes integrados

4. Relatórios API

Backend Core

Tecnologia: NestJS 11, Prisma ORM, PostgreSQL, OpenTelemetry

Responsabilidades:

  • API especializada em relatórios complexos e analytics
  • Processamento de grandes volumes de dados
  • Exportação em múltiplos formatos (Excel, CSV, JSON)
  • Consultas otimizadas ao data warehouse
  • Upload de relatórios para AWS S3

Recursos: ExcelJS para geração de planilhas, Pino logging com OpenTelemetry, event emitter para processamento assíncrono

5. Mensageria ARTESP Proxy

Integração Core

Tecnologia: Java 17, Spring Boot 3.5, Kafka, RabbitMQ, Protocol Buffers, MongoDB

Responsabilidades:

  • Proxy bidirecional entre formato interno (JSON) e ARTESP (Protobuf)
  • Conversão de mensagens JSON para Protocol Buffers conforme ARTESP 001/14
  • Orquestração simultânea com 5 OSAs
  • Validação e retry automático com Resilience4j
  • Auditoria de mensagens em MongoDB (retenção 5 anos)
  • Conformidade com SLAs ARTESP (24h envio, 36h reenvio, 12h resposta)

Recursos: Clean Architecture, circuit breakers, fallback strategies, logging estruturado com rastreamento distribuído

6. Bridge

Integração Core

Tecnologia: Java 17, Spring Boot 3.5, JMS, Spring Cloud Config, RabbitMQ

Responsabilidades:

  • Sistema genérico de bridges JMS/AMQP
  • Suporte a múltiplos brokers (Artemis, ActiveMQ, WebLogic, RabbitMQ)
  • Roteamento bidirecional de mensagens por tipo (passagens, tags, imagens)
  • Recuperação automática de falhas de conexão
  • Configuração dinâmica via Spring Cloud Config

Recursos: Factory Pattern para brokers, Strategy Pattern para roteamento, profiles combinados (ambiente + OSA)

7. Image Sender Service

Backend Core

Tecnologia: Java 17, Spring Boot 3.2, PostgreSQL, RabbitMQ, Kubernetes CronJob

Responsabilidades:

  • Envio automatizado de imagens de passagens para OSAs
  • Execução diária via CronJob (5h da manhã)
  • Consulta de imagens pendentes no PostgreSQL
  • Agrupamento de imagens por transação
  • Publicação em RabbitMQ para distribuição OSAs
  • Atualização de status de processamento

Recursos: Spring Cloud Config opcional, OpenTelemetry para observabilidade, suporte a 3 OSAs (Sem Parar, ConectCar, Veloe)

Fluxos de Integração

Protocolo ARTESP 001/14

Conformidade Regulatória: Toda comunicação com OSAs segue rigorosamente o protocolo ARTESP 001/14, garantindo interoperabilidade e conformidade regulatória. O Backoffice N3 implementa conversão automática de formatos internos (JSON) para o padrão ARTESP (Protocol Buffers).

Fluxo End-to-End de Processamento de Passagem

graph LR subgraph "Etapa 1: Captura" A[Pórtico N1/N2
Captura OCR] -->|JSON| B[Kafka Topic
transacao-operacional] end subgraph "Etapa 2: Processamento" B -->|Consumer| C[Processador LST] C -->|Validação| D{JSON
Schema OK?} D -->|Não| E[DLQ] D -->|Sim| F[Cálculo Tarifa] F --> G[Persistir PostgreSQL] G --> H[Cache Redis] H --> I[Publicar RabbitMQ] end subgraph "Etapa 3: Conversão ARTESP" B -->|Consumer| J[Mensageria Proxy] J -->|JSON → Protobuf| K[Converter ARTESP 001/14] K --> L[Validar Protobuf] end subgraph "Etapa 4: Distribuição OSAs" L --> M[Bridge Engine] M -->|JMS/AMQP| N1[OSA 1 Queue] M -->|JMS/AMQP| N2[OSA 2 Queue] M -->|JMS/AMQP| N3[OSA 3 Queue] end style C fill:#059669,color:#fff style J fill:#f59e0b,color:#fff style M fill:#f59e0b,color:#fff style E fill:#dc2626,color:#fff

Fluxo de Monitoramento AVI

stateDiagram-v2 [*] --> Capturada: Passagem detectada Capturada --> Processando: Enviar para processamento Processando --> AguardandoOSA: Aguardar validação (timeout 5 dias) AguardandoOSA --> Aprovada: OSA retorna validação OK AguardandoOSA --> AVI: Timeout 5 dias AVI --> RecuperacaoAutomatica: Sistema inicia cobrança RecuperacaoAutomatica --> Recuperada: Inadimplente paga RecuperacaoAutomatica --> Inadimplente: Sem pagamento Aprovada --> [*] Recuperada --> [*] Inadimplente --> [*]

SLAs e Timeouts ARTESP

Operação SLA ARTESP Implementação Backoffice N3
Envio de Passagem 24 horas Tempo real (< 2 segundos)
Reenvio em Caso de Falha 36 horas Retry automático com backoff exponencial
Resposta da OSA 12 horas Monitoramento ativo com alertas
Monitoramento AVI 5 dias úteis Sistema automático de timeout e recovery
Auditoria de Mensagens 5 anos MongoDB com retenção configurável

Tipos de Mensagens ARTESP

Tipo Direção Formato Descrição
Passagens Concessionária → OSA Protobuf Transações de passagem para validação
Tags OSA → Concessionária Protobuf Validação de tags veiculares
Imagens Concessionária → OSA Protobuf + Binary Evidências fotográficas de passagens
Processadas OSA → Concessionária Protobuf Confirmação de processamento
Tarifas Concessionária → OSA Protobuf Tabela de tarifas vigentes

Tecnologias Utilizadas

Linguagens e Runtimes

Tecnologia Versão Componentes Justificativa
Java 17 LTS Processador, Mensageria Proxy, Bridge, Image Sender Performance, estabilidade, ecossistema Spring maduro
TypeScript 5.x Portal, BFF, Relatórios API Type safety, produtividade, ecossistema React/Node
Node.js 20.x LTS BFF, Relatórios API Event loop não-bloqueante, NPM ecosystem

Frameworks Backend

Framework Versão Uso
Spring Boot 3.5.4 / 3.2.5 Todos os serviços Java (DI, web, data, messaging)
Spring Data JPA 3.5.4 Persistência relacional com Hibernate
Spring Kafka 3.5.4 Consumo de mensagens Kafka
Spring AMQP 3.5.4 Integração RabbitMQ e JMS
Spring Cloud Config 4.x Configuração centralizada e externalizada
NestJS 11.1.5 BFF e Relatórios API (estrutura modular, DI)

Frontend Stack

Tecnologia Versão Propósito
React 19.0.0 Biblioteca UI declarativa
Vite 6.2.0 Build tool e dev server (HMR rápido)
TailwindCSS 4.0.14 Utility-first CSS framework
Radix UI 16 componentes Componentes acessíveis (a11y)
React Router 7.3.0 Roteamento SPA
Zustand 5.0.3 State management (leve e performático)
Axios 1.8.3 Cliente HTTP com interceptors

Bancos de Dados

Tecnologia Uso Acesso
PostgreSQL 15+ Primary database (transações, usuários, relatórios) Spring Data JPA / Prisma ORM
Redis 7.x Cache distribuído, sessões (timeout 2s) Spring Data Redis / node-cache
MongoDB 6.x Auditoria de mensagens (opcional, retenção 5 anos) Spring Data MongoDB

Message Brokers

Broker Protocolo Uso
Apache Kafka Kafka Protocol Entrada de transações do N1/N2 (JSON), stream processing
RabbitMQ AMQP 0.9.1 Saída para OSAs (Protobuf), comunicação interna
Apache Artemis JMS 2.0 Bridge JMS alternativo
ActiveMQ JMS 1.1 Suporte legacy OSAs
Oracle WebLogic JMS 2.0 Integração OSAs enterprise

Observabilidade

Ferramenta Tipo Uso
OpenTelemetry Tracing Rastreamento distribuído de requisições
SigNoz APM Backend Ingestão e visualização de traces/métricas
Prometheus Métricas Coleta de métricas de runtime e negócio
Micrometer Métricas Abstração de métricas para Spring Boot
Pino / Winston Logging Logs estruturados JSON

DevOps e Infraestrutura

Tecnologia Propósito
Docker Containerização de todos os serviços
Kubernetes Orquestração, auto-scaling, health checks
ArgoCD GitOps e continuous deployment
Spring Cloud Config Configuração centralizada multi-ambiente
AWS S3 Armazenamento de relatórios e evidências
SonarQube Análise estática de código e cobertura

Segurança

Componente Implementação
Autenticação JWT (jsonwebtoken + Passport.js + Spring Security)
Autorização Role-Based Access Control (RBAC)
Comunicação OSAs mTLS (mutual TLS) via VPN site-to-site
HTTP Security Helmet.js, CORS configurado, rate limiting
Bot Protection Cloudflare Turnstile
Secrets Kubernetes Secrets, variáveis de ambiente

Bibliotecas Auxiliares

Segurança e Conformidade

Camadas de Segurança

graph TD A[Usuário/Sistema] --> B{Cloudflare
Turnstile} B -->|Bot Protection| C[Load Balancer] C --> D{JWT
Validation} D -->|Invalid| E[401 Unauthorized] D -->|Valid| F{RBAC
Authorization} F -->|Forbidden| G[403 Forbidden] F -->|Allowed| H[Rate Limiter] H -->|Throttled| I[429 Too Many Requests] H -->|OK| J[Application Layer] J --> K{mTLS VPN} K --> L[OSA Communication] style B fill:#f59e0b,color:#fff style D fill:#059669,color:#fff style F fill:#059669,color:#fff style K fill:#059669,color:#fff

Autenticação e Autorização

JWT (JSON Web Tokens)

Role-Based Access Control (RBAC)

Role Permissões Acesso
Administrador Completo (CRUD, configurações, usuários) Dashboard, Relatórios, Configurações, Gestão Usuários
Gestor Leitura + relatórios Dashboard, Relatórios, Visualização Transações
Operador Leitura básica Dashboard, Consultas
API (Sistema) Integração via API key Endpoints específicos de integração

Comunicação Segura

Comunicação Externa (OSAs)

  • VPN Site-to-Site: Túnel seguro entre concessionária e OSAs
  • mTLS (Mutual TLS): Autenticação mútua com certificados X.509
  • Criptografia: TLS 1.3 com cipher suites recomendados
  • Firewall: Whitelist de IPs OSAs autorizadas
  • Auditoria: Todos os payloads registrados em MongoDB

Comunicação Interna

Proteção de Dados

Aspecto Implementação
Dados em Trânsito TLS 1.3, mTLS para OSAs
Dados em Repouso Criptografia PostgreSQL, MongoDB encryption at rest
Dados Sensíveis Hashing bcrypt para senhas, mascaramento de placas em logs
LGPD/GDPR Anonimização de dados pessoais, política de retenção configurável
Backup Backups criptografados com retenção 30 dias

Conformidade Regulatória

ARTESP 001/14

  • Implementação completa do protocolo de comunicação
  • Formato de mensagens Protobuf conforme especificação
  • SLAs de envio, reenvio e resposta atendidos
  • Auditoria de mensagens com retenção de 5 anos
  • Rastreabilidade completa de transações

Resiliência e Recuperação

Circuit Breaker (Resilience4j)

Retry Strategies

Benefícios Operacionais

Redução de Custos

Desenvolvimento

  • Eliminação de integrações customizadas por OSA
  • Abstração de complexidade do protocolo ARTESP
  • Redução de 80% no tempo de onboarding de novas OSAs

Operacional

  • Automação de monitoramento AVI (zero intervenção manual)
  • Recuperação automática de inadimplentes
  • Redução de 60% em chamados de suporte

Infraestrutura

  • Auto-scaling reduz custos em períodos de baixa demanda
  • Cache Redis diminui carga em banco de dados
  • Arquitetura cloud-native permite pay-as-you-go

Aumento de Receita

Gestão de Riscos

Risco Mitigação Backoffice N3 Impacto
Não Conformidade ARTESP Implementação certificada do protocolo 001/14 Zero multas regulatórias
Falha de Comunicação OSA Circuit breaker + retry + DLQ 99.9% de entrega garantida
Perda de Dados Auditoria completa + backup criptografado Rastreabilidade 100%
Indisponibilidade Auto-scaling K8s + health checks SLA 99.9% uptime
Vazamento de Dados mTLS + VPN + encryption at rest Conformidade LGPD/GDPR

Visibilidade e Controle

Dashboard em Tempo Real

Observabilidade Distribuída

Time to Market

Onboarding de Nova OSA

Sem Backoffice N3: 3-6 meses (desenvolvimento, homologação, certificação)

Com Backoffice N3: 2-4 semanas (configuração, testes, go-live)

Redução: 85% no tempo de integração

Escalabilidade

Dimensão Capacidade Atual Limite Arquitetural
Transações/segundo 500 TPS 10.000 TPS (auto-scaling)
Concessionárias Configurável Ilimitado (multi-tenancy)
OSAs 5 simultâneas 20+ (adição via config)
Usuários Dashboard 100 concorrentes 1.000+ (horizontal scaling)
Armazenamento 500GB/mês Petabytes (S3 + PostgreSQL managed)

Integração com Portal Pedágio Eletrônico

O Backoffice N3 integra-se com o ecossistema completo do Portal Pedágio Eletrônico, complementando funcionalidades de cobrança e gestão financeira.

Serviços Relacionados

Core API (Portal Pedágio)

Tecnologia: NestJS, PostgreSQL, Prisma ORM, RabbitMQ

Responsabilidades:

  • Gestão de transações de pedágio para usuários finais
  • Processamento de pedidos e pagamentos (Pagar.me)
  • Sistema de autenticação e permissões (RBAC)
  • Notificações e comunicações com usuários
  • Gestão de comprovantes fiscais

Integração com Backoffice N3: Recebe confirmações de transações processadas via RabbitMQ para atualização de status de pedidos.

Core Banking API

Tecnologia: Java 17, Spring Boot 3.5, PostgreSQL, RabbitMQ, Redis

Responsabilidades:

  • Core banking para gestão de contas (pré-pago e pós-pago)
  • CRUD de clientes (Pessoa Física e Jurídica)
  • Processamento de transações financeiras (débitos e créditos)
  • Garantia de idempotência e auditoria financeira
  • Integração assíncrona via RabbitMQ

Integração com Backoffice N3: Processa transações financeiras originadas do Processador Passagens LST via topic RabbitMQ retorno.transacaofinanceira.topic.

Fluxo de Integração Backoffice N3 + Portal Pedágio

sequenceDiagram participant N3 as N3 Processador LST participant RMQ as RabbitMQ participant Banking as Core Banking API participant Portal as Core API (Portal) participant User as Usuário Final N3->>RMQ: Publicar transação financeira RMQ->>Banking: Consumir transação Banking->>Banking: Processar débito/crédito Banking->>Banking: Validar idempotência Banking->>RMQ: Publicar resultado RMQ->>Portal: Consumir resultado Portal->>Portal: Atualizar status pedido Portal->>User: Notificar confirmação

Separação de Responsabilidades

Responsabilidade N3 Portal Pedágio
Integração OSAs Completa (ARTESP 001/14) -
Processamento Passagens Tempo real (validação, tarifação) -
Dashboard Concessionária Completo (métricas operacionais) -
Gestão Financeira Inicia transações Processa (Core Banking)
Portal Usuário Final - Completo (pedidos, pagamentos)
Notificações Usuários - Completo (email, SMS, push)

Nota Importante: O Portal Pedágio Eletrônico (Core API + Core Banking) é referenciado nesta documentação apenas para contextualização do ecossistema completo. O foco comercial do Backoffice N3 está na plataforma de integração entre concessionárias e OSAs.

Infraestrutura e Escalabilidade

Arquitetura de Deployment

graph TB subgraph "Internet" Users[Usuários] OSAs[OSAs Externas] end subgraph "Load Balancer Layer" LB[Load Balancer
AWS ALB / NGINX] end subgraph "Kubernetes Cluster" subgraph "Frontend Namespace" Portal1[Portal Pod 1] Portal2[Portal Pod 2] BFF1[BFF Pod 1] BFF2[BFF Pod 2] end subgraph "Backend Namespace" Proc1[Processador Pod 1] Proc2[Processador Pod 2] Proxy1[Mensageria Proxy Pod 1] Bridge1[Bridge Pod 1] ImageCron[Image Sender CronJob] end subgraph "Data Namespace" PG[PostgreSQL StatefulSet] Redis[Redis StatefulSet] Kafka[Kafka StatefulSet] end end subgraph "External Services" S3[AWS S3] SigNoz[SigNoz APM] ConfigServer[Spring Cloud Config] end Users -->|HTTPS| LB LB --> Portal1 LB --> Portal2 Portal1 --> BFF1 Portal2 --> BFF2 Kafka --> Proc1 Kafka --> Proc2 Kafka --> Proxy1 Proc1 --> PG Proc2 --> PG Proc1 --> Redis Proc2 --> Redis Proxy1 --> Bridge1 Bridge1 -->|VPN mTLS| OSAs ImageCron --> PG BFF1 --> S3 BFF2 --> S3 Proc1 -.->|Telemetry| SigNoz Proxy1 -.->|Telemetry| SigNoz Bridge1 --> ConfigServer

Ambientes

Ambiente Propósito Recursos Dados
Desenvolvimento Desenvolvimento local Docker Compose local Mocks + dados sintéticos
Homologação Testes integrados + UAT Kubernetes (2 nodes) Subset produção anonimizado
Produção Operação 24/7 Kubernetes (5+ nodes, auto-scaling) Dados reais

Estratégia de Deployment

GitOps com ArgoCD

Rolling Update

Auto-Scaling

Horizontal Pod Autoscaler (HPA)

Serviço Min Replicas Max Replicas Métrica Target
Dashboard Portal 2 10 CPU 70%
Dashboard BFF 2 10 CPU 70%
Processador LST 2 20 Kafka Lag < 1000 msgs
Mensageria Proxy 2 15 Kafka Lag < 500 msgs
Relatórios API 1 5 CPU + Memory 70% / 80%

Cluster Autoscaler

Disaster Recovery

Backup Strategy

Componente Frequência Retenção RPO RTO
PostgreSQL Contínuo (WAL) + Snapshot diário 30 dias < 5 min < 1 hora
MongoDB Snapshot diário 5 anos < 24 horas < 4 horas
Redis RDB snapshot a cada 1 hora 7 dias < 1 hora < 30 min
Kafka Replicação 3x + snapshot diário 14 dias < 1 min < 15 min
S3 (Relatórios) Versionamento + replicação cross-region Indefinido 0 < 5 min

High Availability

Segurança de Infraestrutura

Monitoramento e Observabilidade

Os Três Pilares

Métricas

Stack: Prometheus + Micrometer + Grafana

  • Taxa de requisições (RPS)
  • Latência (p50, p95, p99)
  • Taxa de erro (4xx, 5xx)
  • Saturação (CPU, memória, disco)
  • Métricas de negócio (transações/min, receita)

Logs

Stack: Pino/Winston + ELK/Loki

  • Logs estruturados JSON
  • Correlation ID em todas as requisições
  • Níveis: ERROR, WARN, INFO, DEBUG
  • Contexto completo (user, transaction, service)
  • Retenção: 90 dias (hot), 1 ano (cold)

Traces

Stack: OpenTelemetry + SigNoz

  • Rastreamento distribuído end-to-end
  • Identificação de bottlenecks
  • Dependency mapping automático
  • Análise de latência por span
  • Sampling inteligente (100% errors, 10% success)

Dashboards Operacionais

Golden Signals (por serviço)

Signal Métrica Threshold Warning Threshold Critical
Latency Tempo de resposta p95 > 2 segundos > 5 segundos
Traffic Requisições por segundo < 10 RPS (baixo tráfego) N/A
Errors Taxa de erro > 1% > 5%
Saturation CPU / Memória > 80% > 95%

Métricas de Negócio

Alertas Configurados

Alertas Críticos (PagerDuty)

Alertas Warning (Slack)

SLA e SLO

Serviço SLO (Service Level Objective) SLA (Service Level Agreement)
Dashboard Portal + BFF 99.9% disponibilidade, p95 < 1s 99.5% uptime mensal
Processador Passagens 99.95% disponibilidade, p95 < 2s 99.9% uptime mensal
Mensageria ARTESP Proxy 99.99% disponibilidade, 100% SLA ARTESP 99.95% uptime mensal
Entrega OSAs 99.9% mensagens entregues < 24h 99.5% conformidade ARTESP

Rastreabilidade End-to-End

graph LR A[Requisição] -->|Correlation ID| B[Portal] B -->|Propagação Header| C[BFF] C -->|Propagação Header| D[APIs Backend] D -->|Kafka Header| E[Processador] E -->|RabbitMQ Header| F[Mensageria Proxy] F -->|Auditoria MongoDB| G[Log Completo] B -.->|Trace| H[OpenTelemetry] C -.->|Trace| H D -.->|Trace| H E -.->|Trace| H F -.->|Trace| H H --> I[SigNoz APM] style A fill:#3b82f6,color:#fff style G fill:#059669,color:#fff style I fill:#8b5cf6,color:#fff

Exemplo de Trace Distribuído

Trace ID: 7f3c9b2a-4e1d-4b8f-9c3a-2d5e6f7a8b9c
Duration: 1.847s

Span 1: Portal React → BFF (125ms)
  - User Action: Exportar Relatório
  - HTTP GET /api/reports/transactions?period=last_month

Span 2: BFF → Relatórios API (1.650ms)
  - HTTP POST /reports/generate
  - Query PostgreSQL: 1.520ms (32.500 rows)
  - Generate Excel: 95ms

Span 3: BFF → AWS S3 Upload (72ms)
  - Presigned URL generation: 12ms
  - Upload 2.3MB: 60ms

Total: 1.847s (p95 threshold: 2s) ✓ OK

Glossário

Definições dos principais termos técnicos utilizados nesta documentação.

A

API (Application Programming Interface)
Conjunto de definições e protocolos para integração entre aplicações. Permite que diferentes sistemas se comuniquem de forma padronizada através de requisições HTTP/REST.
ARTESP 001/14
Protocolo oficial de comunicação entre concessionárias de rodovias e Operadoras de Serviços de Arrecadação (OSAs), definido pela Agência de Transporte do Estado de São Paulo. Estabelece o formato e regras para troca de mensagens em sistemas de pedágio eletrônico.
ArgoCD
Ferramenta de entrega contínua (CD) para Kubernetes que implementa GitOps, permitindo que a configuração da infraestrutura seja versionada em repositórios Git e automaticamente sincronizada com o cluster.

B

BFF (Backend for Frontend)
Camada intermediária entre o frontend e os serviços de backend que agrega, transforma e otimiza dados especificamente para as necessidades da interface do usuário. Reduz o número de chamadas e simplifica a lógica no cliente.

C

Circuit Breaker
Padrão de resiliência que interrompe temporariamente chamadas a serviços que estão falhando, evitando sobrecarga e permitindo recuperação. Funciona como um "disjuntor" que abre quando detecta muitas falhas.
CRUD
Acrônimo para Create, Read, Update, Delete - operações básicas de manipulação de dados em sistemas de informação.

D

Docker
Plataforma de containerização que permite empacotar aplicações e suas dependências em containers isolados, garantindo consistência entre ambientes de desenvolvimento, teste e produção.
DUF (Desconto do Usuário Frequente)
Programa de desconto progressivo regulamentado pela ARTESP para usuários de pedágio eletrônico (AVI) que utilizam frequentemente a mesma praça no mesmo sentido. O desconto é aplicado automaticamente a partir da segunda passagem no mês, podendo chegar até 20% para veículos de categoria 1 (passeio), com percentuais progressivos até a 30ª passagem. O Backoffice N3 calcula e aplica automaticamente os descontos DUF conforme as regras de cada praça de pedágio.

F

Free Flow
Sistema de pedágio eletrônico sem cancelas ou barreiras físicas, onde a cobrança é feita automaticamente através de identificação por tags RFID ou reconhecimento de placas (OCR) enquanto o veículo trafega em velocidade normal. O Backoffice N3 também suporta praças tradicionais com cancelas e leitura de tags RFID.

J

JMS (Java Message Service)
API Java para sistemas de mensageria que permite comunicação assíncrona entre componentes através de filas e tópicos de mensagens.
JSON (JavaScript Object Notation)
Formato leve de troca de dados baseado em texto, fácil de ler e escrever para humanos e de interpretar para máquinas. Amplamente utilizado em APIs REST.
JWT (JSON Web Token)
Padrão aberto (RFC 7519) para transmissão segura de informações entre partes como um objeto JSON assinado digitalmente. Utilizado para autenticação e autorização em APIs.

K

Kafka (Apache Kafka)
Plataforma distribuída de streaming de eventos de alta performance, utilizada para processamento de grandes volumes de mensagens em tempo real com garantias de entrega e ordenação.
Kubernetes (K8s)
Plataforma open-source de orquestração de containers que automatiza o deployment, scaling e gerenciamento de aplicações containerizadas em clusters.

M

Microserviços
Arquitetura de software onde a aplicação é dividida em serviços pequenos, independentes e especializados que se comunicam através de APIs. Cada microserviço pode ser desenvolvido, deployado e escalado de forma independente.
MongoDB
Banco de dados NoSQL orientado a documentos que armazena dados em formato JSON-like (BSON), oferecendo flexibilidade de schema e alta performance para grandes volumes.
mTLS (Mutual TLS)
Autenticação mútua baseada em certificados TLS onde tanto cliente quanto servidor verificam a identidade um do outro, garantindo comunicação segura e autenticada entre serviços.

O

Observabilidade
Capacidade de entender o estado interno de um sistema através de suas saídas (logs, métricas e traces). Permite detectar, diagnosticar e resolver problemas de forma proativa.
OCR (Optical Character Recognition)
Tecnologia de reconhecimento óptico de caracteres que converte imagens de texto (como placas de veículos) em texto digital editável.
OpenTelemetry
Framework open-source para instrumentação, geração, coleta e exportação de telemetria (métricas, logs e traces) de aplicações distribuídas.
OSA (Operadora de Serviços de Arrecadação)
Empresa autorizada a operar sistemas de cobrança eletrônica de pedágio, fornecendo tags e gerenciando contas de usuários. Exemplos: Sem Parar, ConectCar, Veloe.

P

PostgreSQL
Banco de dados relacional open-source avançado, com suporte a transações ACID, índices complexos, full-text search e extensibilidade.
Protobuf (Protocol Buffers)
Formato de serialização de dados binário desenvolvido pelo Google, mais compacto e rápido que JSON ou XML. Utilizado para comunicação eficiente entre serviços.

R

RabbitMQ
Message broker (intermediário de mensagens) que implementa o protocolo AMQP, permitindo comunicação assíncrona entre aplicações através de filas e tópicos de mensagens.
RBAC (Role-Based Access Control)
Sistema de controle de acesso baseado em papéis/funções, onde permissões são atribuídas a roles e usuários recebem roles, simplificando o gerenciamento de autorizações.
Redis
Banco de dados em memória (in-memory) de alta performance, utilizado para cache, sessions, filas e armazenamento de dados temporários com acesso extremamente rápido.
REST (Representational State Transfer)
Estilo arquitetural para APIs web que usa HTTP e seus métodos (GET, POST, PUT, DELETE) para operações sobre recursos identificados por URLs.
RFID (Radio-Frequency Identification)
Tecnologia de identificação por radiofrequência utilizada em tags de pedágio eletrônico para identificar veículos à distância sem necessidade de contato físico.

S

SigNoz
Plataforma open-source de observabilidade que agrega logs, métricas e traces distribuídos, oferecendo visualizações e alertas para monitoramento de aplicações.
Spring Boot
Framework Java que simplifica o desenvolvimento de aplicações enterprise, fornecendo configuração automática, servidor embarcado e convenções sobre configuração.
Spring Cloud Config
Servidor de configuração centralizada do ecossistema Spring que permite gerenciar configurações de múltiplos ambientes em repositórios Git versionados.

T

TailwindCSS
Framework CSS utility-first que fornece classes pré-definidas para construção rápida de interfaces responsivas sem escrever CSS customizado.
TLS (Transport Layer Security)
Protocolo criptográfico que fornece segurança nas comunicações de rede através de criptografia, autenticação e integridade de dados.
TypeScript
Superset do JavaScript que adiciona tipagem estática opcional, permitindo detecção de erros em tempo de desenvolvimento e melhor tooling para IDEs.

V

Vite
Build tool moderna e extremamente rápida para aplicações frontend, oferecendo hot module replacement (HMR) instantâneo e builds otimizados para produção.