docs: um passeio guiado pela arquitetura, e o mapa vira diagrama

[kerlonr]

O que é

Faltava um documento que respondesse "como isso funciona?" para quem nunca viu o projeto. O docs/ explica como instalar cada frente e o contrato-mqtt.md explica o formato das mensagens — mas nenhum dos dois conta a história de ponta a ponta.

COMO-FUNCIONA.md conta, em quinze minutos e com diagramas Mermaid:

• as duas jornadas que definem o repositório: a de ida (dedo no botão até o motor girar, em oito passos) e a de volta (posição do GPS até o gráfico no celular, em sete);
• os cinco serviços do Pi numa tabela: o que cada um assina, o que publica, o que faz;
• as três camadas de motores/, e por que as duas de baixo rodam sem robô;
• o barramento MQTT inteiro numa tabela — inclusive os dois tópicos que ainda não têm consumidor;
• as três camadas independentes de segurança de movimento, e por que são três: cada uma cobre a falha da anterior;
• as duas armadilhas que já custaram caro (dois brokers na 1883, e os serviços não instalados no robô).

O mapa ganhou um diagrama de verdade

O ASCII de 30 linhas do MAPA-COMUNICACAO.md era legível no editor e não dizia quem falava com quem sem esforço. Virou Mermaid — com duas ressalvas escritas embaixo, porque um diagrama bonito que mostra serviços inexistentes é pior que nenhum:

1. as setas para os serviços do pi/services/ são planta, não construção (ver a §0);
2. os tópicos de voz e rota ainda não têm quem os consuma.

Verificação

• 135 testes continuam passando (API 37, motores 52, roteador 30, wifi 16)
• o diagrama do mapa e os 4 do documento novo foram validados com o mermaid-cli

🤖 Generated with Claude Code

https://claude.ai/code/session_0173mr3mDsAKQuPUNaPghe9v