A viagem acontece no campo.
O sistema precisa acompanhar.
Uma operação logística não acontece só no navegador. Existe um motorista usando o app, dados de localização sendo coletados, informações de viagem circulando entre dispositivos e uma equipe acompanhando tudo pelo painel web.
O app precisa preservar os dados de localização quando a conexão cai e sincronizá-los com o backend quando há conexão. O painel usa esses dados para acompanhar a operação.
Concebi a arquitetura.
Implementei o núcleo.
Minha responsabilidade abrangeu backend e dados, integração do GPS, interfaces web e mobile e publicação do aplicativo.
O que assumi no projeto
- Arquitetura central, APIs, dados e integração Cloudflare/Supabase.
- Integração entre o app do motorista e o painel operacional pela Core API.
- Integração do SDK GPS, investigação do comportamento offline e sincronização por lotes.
- Diagnósticos técnicos e evolução da visualização de rotas.
- Preparação e publicação do aplicativo para iOS e Android.
A estrutura por trás
do produto.
O mapa mostra as principais responsabilidades e conexões. Amplie para explorar o fluxo ou escolha uma camada para entender seu papel no sistema.
Ler o diagrama em texto
O app persiste dados no SQLite e envia lotes para a Core API Hono. O painel Next.js e a visualização pública usam o mesmo backend. O Core valida sessões com Supabase Auth, aplica regras de negócio e acessa PostgreSQL com PostGIS, evidências privadas no R2 e documentos privados no Supabase Storage. As setas mostram requisições e dependências selecionadas, não todos os caminhos de rede.
Projetar para o aparelho, não só para a requisição.
O app separa telas, domínio e integrações. A persistência usa SQLite/Drizzle, com SDK de localização em segundo plano e fluxos próprios de sincronização. Operação offline não significa execução ilimitada em segundo plano: permissões, sistema operacional e conexão continuam importando.
Uma retentativa não pode virar outro lote.
O backend identifica lotes GPS por clientBatchId e checksum. Assim, o reenvio pode ser tratado como repetição, não como nova evidência. App e servidor também precisam concordar sobre o estado dos lotes e a ordenação dos dados.
Manter as regras de negócio no backend.
Rotas validam entradas com Zod e chamam services; repositories cuidam da persistência e mappers moldam a resposta. O backend resolve organização e autorização. GPS é evidência; a quilometragem usa distância declarada e leituras/fotos do odômetro.
Dar visibilidade sem expor os arquivos.
O painel consome o Core por TanStack Query. Evidências de viagem ficam no R2 privado; avatares e documentos usam Supabase Storage privado. Acesso assinado e verificações do backend conectam a interface aos arquivos.
O que escolhi.
Os compromissos envolvidos.
01Tornar a sincronização idempotente.Reenviar sem duplicar a evidência.
Escolha de arquitetura
Usar identificador e checksum do lote ao receber pontos GPS. O transporte pode repetir a entrega sem criar outro lote lógico a cada tentativa.
A contrapartida
Idempotência exige um contrato persistente: identidade, conflitos e estado precisam permanecer coerentes. Ela não elimina as restrições do sistema operacional nem da conexão.
02Separar evidência GPS de quilometragem declarada.O trajeto observado não substitui a distância declarada.
Escolha de arquitetura
Usar distância declarada e leituras/fotos do odômetro para a quilometragem. Preservar GPS ordenado e simplificá-lo para exibir a rota, sem transformar sinal ruidoso na distância comercial.
A contrapartida
A interface precisa diferenciar o que foi declarado do que foi coletado. Exibir uma rota não prova que o GPS registrou todos os trechos da viagem.
03Manter a autoridade no Core.A mesma regra para web e aplicativo.
Escolha de arquitetura
Centralizar contexto da organização, permissões e regras no backend Hono. Separar rotas, validação, services, repositories e mapeamento da resposta.
A contrapartida
Web e app precisam respeitar contratos estáveis. Ter mais interfaces não deve criar versões concorrentes da mesma permissão ou regra de negócio.
Da decisão
à implementação.
Backend central e APIs
Backend, dados e infraestrutura conectando aplicativo e painel.
Rastreamento e sincronização
Integração da SDK, investigação de lotes e evolução das rotas.
Interface e integração com APIs
Implementação e ajustes visuais em web e app, conectados ao backend central.
Publicação para iOS e Android
Participei da preparação e publicação do aplicativo ALP para iOS e Android.
Esse trabalho chega ao aparelho do motorista, ao painel da operação e às lojas de aplicativos, com links no início deste case.