Onde está cada parte do código?

Objetivo desta página: conseguir abrir o repositório sem tentar ler tudo em ordem alfabética. Ela acompanha a história de uma medição, mas agora mostra onde cada decisão aparece no código.

Primeiro, entenda as pastas

O package.json da raiz declara apps/* e packages/* como npm workspaces. Isso significa que há várias aplicações e bibliotecas no mesmo repositório, com dependências compartilhadas.

Pasta	Papel nesta trilha
apps/inverter-to-mqtt/	Aplicação que lê inversores e publica medições.
apps/mqtt-to-db/	Aplicação que recebe, prepara e grava medições.
packages/mqtt/	Biblioteca com o contrato de tópico, payload, publicação e assinatura.
packages/db/	Schema Prisma e acesso compartilhado ao PostgreSQL.
mosquitto/	Configuração do broker; não é um pacote TypeScript.
grafana/	Dashboards e configuração da visualização.

Também existem apps/admin/ e apps/mqtt-device-simulator/. A trilha inicial não detalha seus fluxos; o Admin é tratado em segurança e alterações e referência da API. Uma aplicação inicia um processo; um pacote fornece código reutilizado por outras partes. O nome @campus/mqtt em um import aponta para o pacote local, não para o servidor Mosquitto.

Como seguir o lado que publica

Abra estes arquivos nesta ordem, procurando primeiro as funções indicadas:

1. apps/inverter-to-mqtt/src/main.ts — runInverterToMqtt() reúne configuração, banco, cliente MQTT e runtime. Essa é a entrada executável da aplicação.
2. apps/inverter-to-mqtt/src/runtime.ts — createInverterToMqttRuntime() organiza o ciclo. Dentro dele, collectFromSource() conecta, chama readTelemetry(), transforma e publica.
3. apps/inverter-to-mqtt/src/CollectorFactory.ts e ICollector.ts — mostram como a chave do inventário escolhe um adapter e qual formato ele precisa devolver.
4. apps/inverter-to-mqtt/src/mapper.ts — toTelemetryMetrics() traduz os nomes da leitura para as chaves do contrato MQTT.
5. packages/mqtt/src/publisher.ts e contract.ts — publishTelemetry() valida e envia.

Você não precisa compreender o conteúdo dos registradores Modbus nessa primeira leitura. Procure somente a passagem de um objeto para o próximo. Não execute o coletor para estudar: ele pode conectar aos inversores reais.

Como seguir o lado que recebe

1. apps/mqtt-to-db/src/main.ts — runMqttToDb() reúne o cliente MQTT, o banco e o runtime.
2. packages/mqtt/src/subscriber.ts — subscribeTelemetry() transforma o texto recebido em uma mensagem classificada como válida ou inválida.
3. apps/mqtt-to-db/src/runtime.ts e queue.ts — recebem a mensagem e a processam em fila.
4. apps/mqtt-to-db/src/index.ts — processTelemetryMessage() chama preparação e persistência.
5. apps/mqtt-to-db/src/message-processor.ts — prepareTelemetry() prepara os dados sem fazer operações de entrada e saída.
6. apps/mqtt-to-db/src/persistence.ts — persistTelemetry() decide quais registros gravar.

Se uma função é passada como argumento, como processMessage no runtime, volte ao arquivo main.ts para descobrir qual implementação real foi entregue. Isso costuma ser mais útil que tentar adivinhar pelo nome da variável.

Uma forma de estudar sem se perder

Em cada arquivo, responda três perguntas antes de olhar detalhes de TypeScript:

1. O que este arquivo recebe?
2. O que ele devolve ou envia?
3. Ele só transforma dados, ou conversa com algo externo?

Se a resposta à terceira pergunta for “conversa com algo externo”, trate qualquer execução com cuidado: broker, banco, hardware e produção têm regras próprias. Para estudar a lógica de prepareTelemetry() sem abrir conexões, siga para código explicado.

Mapa revisto em 2026-10-06 contra o package.json da raiz e os arquivos citados.