Aparência
Da leitura ao gráfico
O sistema é formado por programas com responsabilidades distintas. Para entender a arquitetura, acompanhe o que acontece com uma medição desde o inversor até sua apresentação no Grafana.
O fluxo principal em seis etapas
Leia de 1 a 6: a seta liga o fim da primeira linha ao início da segunda. São componentes lógicos, não seis computadores físicos. As pequenas curvas são símbolos ilustrativos, não dados da usina. Ampliar o diagrama.
| Etapa | O que acontece | Onde está no projeto |
|---|---|---|
| 1 · Inversores | Respondem às consultas de medição | Equipamentos Solis e SAJ |
| 2 · Coletor | Escolhe o adapter, interpreta e publica as leituras | apps/inverter-to-mqtt |
| 3 · Mosquitto | Encaminha as mensagens aos assinantes | Broker MQTT |
| 4 · Ingestão | Confere a mensagem, prepara os registros e solicita a gravação | packages/mqtt e apps/mqtt-to-db |
| 5 · PostgreSQL | Armazena catálogo, medições e mensagens recebidas | Schema em packages/db |
| 6 · Grafana | Consulta o histórico para gráficos e regras de alerta | Dashboards e provisioning em grafana/ |
Essa separação permite tratar as diferenças de comunicação na coleta. O consumidor trabalha com o contrato comum, em vez de precisar conhecer o mapa de registradores de cada inversor.
O que uma mensagem carrega?
O coletor converte os nomes internos para as chaves do contrato MQTT. Por exemplo, powerW vira power_w. A mensagem contém o instante atribuído à leitura e um conjunto de métricas.
Exemplo fictício para estudo, sem identificador de equipamento real:
json
{
"ts": "2026-10-20T12:00:00Z",
"metrics": {
"power_w": 2000,
"energy_today_kwh": 6.2
}
}No coletor, ts é gerado pelo relógio da aplicação depois da leitura. Na ingestão, measuredAt guarda esse instante e receivedAt registra a chegada. Se a mensagem omitir ts, a chegada é usada como aproximação.
Uma mensagem vira mais de um registro
Identificar
Encontrar ou cadastrar o dispositivo e as definições das métricas.
Registrar
Guardar uma medição numérica para cada chave: no exemplo, duas linhas.
Preservar
Guardar também a mensagem original para inspeção.
prepareTelemetry() organiza os dados sem acessar a rede ou o banco. persistTelemetry() executa a persistência. Para uma mensagem válida, catálogo, medições e registro bruto participam da mesma transação.
Uma mensagem inválida segue outro caminho: é registrada com o erro, sem criar medições a partir dela. A transação evita uma gravação parcial; ela não elimina por si só entregas repetidas do MQTT.
Onde entram o inventário e o Admin?
O fluxo principal não mostra todas as relações. Antes de coletar, o programa consulta o inventário no banco para saber quais fontes estão habilitadas e qual adapter usar. O Admin consulta e permite edições restritas no catálogo; o Grafana consulta o histórico.
O Admin também apresenta informações resumidas dos alertas. Ele não executa a coleta nem envia comandos elétricos aos inversores. Para a divisão entre processos, imagens e volumes, veja Docker e ambientes.
Aprofunde uma parte de cada vez
Comece por mensagens MQTT, acompanhe a organização do código e leia uma função de preparação explicada. A persistência detalha a gravação; fila e encerramento explica seus limites.
Revisão: 21/10/2026. Fontes: runtime e mapper do coletor; contrato e subscriber de packages/mqtt; message-processor.ts, persistence.ts e runtime do mqtt-to-db; schema Prisma. Artigo SNCT 2026, versão 1.1, como referência narrativa. Ilustração gerada com IA e conferida contra o fluxo principal.