Louvando

Visão Geral

O Louvando resolve um problema bem específico e recorrente de músicos de igreja: encontrar, em segundos, cifra, tom correto e áudio de referência para um louvor que muitas vezes é decidido na hora, com conexão ruim e alta pressão de contexto (um culto em andamento). Antes, a alternativa eram sites lentos, PDFs espalhados, falta de transposição automática e nenhuma busca por trecho de letra.

Começou como uma ferramenta pessoal para uso em minha própria comunidade e com amigos músicos. Conforme o número de louvores cadastrados crescia e o feedback positivo se consolidava, ficou claro que a dor era compartilhada por igrejas de várias denominações. O objetivo se cristalizou em uma frase: entregar uma busca rápida, precisa e utilizável mesmo com 3G instável dentro de um templo.

Atuei sozinho em todo o ciclo: ideação, modelagem de domínio, arquitetura, back-end em Node.js, front-end em Next.js, banco de dados com PostgreSQL + pgvector, fila assíncrona com Redis/Bull, PWA com modo offline, integrações de autenticação social e pipeline de deploy. O projeto vem sendo mantido e evoluído continuamente por mais de 4 anos.

Hoje, o Louvando serve uma base de mais de 1.600 louvores com cifras, tom base, transposição dinâmica e referências de áudio. A busca semântica retorna resultados em menos de 1 segundo, o modo offline cobre o caso real de perda de sinal no meio do culto e a plataforma atende cerca de 12.000 usuários ativos por mês.

Diferencial Principal

O diferencial do Louvando não é “mais um site de cifras”, mas a combinação de três aspectos ao mesmo tempo: busca semântica realmente rápida em português, experiência PWA offline pensada para uso em culto e uma arquitetura que trata letras e cifras como entidades diferentes para preservar a qualidade da busca.

Em vez de depender apenas de busca textual por título, a plataforma usa embeddings vetoriais (pgvector + HNSW) para permitir que o músico encontre um louvor digitando qualquer trecho de letra - mesmo com erros ou variações. Essa busca roda dentro do próprio PostgreSQL, evitando a complexidade de sincronizar múltiplos sistemas.

A experiência offline também é tratada como requisito de primeira classe: o service worker cacheia buscas recentes e louvores visitados, permitindo que o músico continue usando o app mesmo quando o 4G cai ou oscila dentro do templo. E todo o fluxo de transposição de acordes foi desenhado para não interferir na indexação semântica, garantindo relevância de resultado sem sacrificar usabilidade para o músico.

Arquitetura

• Aplicação Web (Next.js 13 + PWA): Interface principal usada em navegadores mobile e desktop, com Server Components, Server Actions para chamadas otimizadas à API e service worker para cache offline de assets e dados.
• API HTTP (Node.js + Express): Camada de back-end que expõe endpoints REST para autenticação, cadastro de louvores, busca textual e semântica, transposição, geração de playlists e administração.
• Camada de Domínio (TypeScript): Serviços de aplicação com injeção de dependências, responsáveis por orquestrar repositórios, provedores de embedding, storage e filas sem acoplar regras de negócio à infra.
• Banco de Dados Relacional (PostgreSQL + TypeORM): Armazena louvores, letras limpas (raw_lyrics), conteúdos com cifras, metadados de áudio, usuários e histórico de uso, com migrations versionadas.
• Extensão Vetorial (pgvector + índice HNSW): Mantém embeddings de títulos + letras para busca semântica aproximada com cosine similarity diretamente no PostgreSQL.
• Motor de Busca Textual (OpenSearch): Indexa campos textuais para buscas mais tradicionais por título ou artista, complementando a camada vetorial quando necessário.
• Fila Assíncrona (Redis + Bull): Gerencia jobs de geração de embeddings, backfill da base legada, processamento de uploads e tarefas não-críticas, com retry, concorrência controlada e monitoramento.
• Provedor de Embeddings (DeepInfra + BGE-M3): Serviço externo chamado pela API para gerar embeddings de alta qualidade em português, substituindo um modelo self-hosted que causava alta latência.
• Armazenamento de Arquivos (AWS S3): Guarda áudios de referência e outros assets pesados, desacoplando o armazenamento de mídia do servidor de aplicação.
• Autenticação (JWT + NextAuth): Combina JSON Web Tokens na API com NextAuth no front para login via Google e Facebook, mantendo sessões seguras e simples de integrar com o PWA.
• Observabilidade (Sentry): Coleta erros de front e back, permitindo identificar gargalos reais de performance e problemas específicos de dispositivos usados em culto.

Destaques Técnicos

• Migração da geração de embeddings de um modelo local via Ollama (latência de 12–18s por query) para BGE-M3 na DeepInfra, reduzindo o tempo de resposta da busca semântica para abaixo de 1s sem quebrar a lógica de domínio graças a uma abstração EmbeddingProvider.
• Implementação de uma fila de backfill com Redis + Bull para gerar embeddings de mais de 1.600 louvores em background, com controle de concorrência e retry, sem afetar a disponibilidade da API em produção.
• Separação explícita entre raw_lyrics (letra limpa para indexação) e texto com cifras para exibição, utilizando um LyricsConverterProvider baseado em LLM para limpar anotações de acordes e manter a busca semântica consistente.
• PWA com service worker configurado para cache inteligente de assets estáticos e respostas de API de louvores já visitados, garantindo continuidade de uso mesmo com perda de sinal no meio do culto.
• Uso de pgvector com índice HNSW e cosine similarity diretamente no PostgreSQL, eliminando a necessidade de um banco vetorial separado e simplificando a consistência entre dados textuais e embeddings.
• Padronização de provedores de infraestrutura (EmbeddingProvider, StorageProvider, MailProvider) com injeção de dependências, permitindo trocar de Ollama para DeepInfra e de disco local para S3 sem reescrever regras de negócio.
• Integração de Next.js 13 com shadcn/ui, TailwindCSS e D3.js para entregar uma UI responsiva, acessível e preparada para futuras visualizações (como estatísticas de uso e repertórios).