Flutter na prática: construindo um app de cifras com scraping, API própria e arquitetura escalável

Nos últimos meses tenho trabalhado com IA, automações e backend, mas senti a necessidade de voltar para um ponto fundamental: interface e experiência mobile com controle total da stack.

Foi daí que nasceu um projeto interno de estudo:

👉 Um app de cifras para violão desenvolvido com Flutter, integrado a uma API própria e com suporte a scraping controlado.

Mas a ideia aqui não é o app em si.

O foco é a arquitetura.

O objetivo do projeto

Construir um sistema completo que envolva:

• Aplicação mobile multiplataforma (Flutter)

• Backend próprio (Python com FastAPI)

• Integração com fonte externa (Cifra Club via scraping)

• Normalização e estruturação de dados musicais

• Base evolutiva para API própria no futuro

Tudo isso seguindo um princípio simples:

não criar apenas um app, mas um sistema escalável desde o início.

Arquitetura definida

O fluxo foi pensado para evitar acoplamento direto com scraping:

Flutter App
↓
API própria
↓
Scraper (cifraclub-api via Docker)
↓
Cifra Club

Essa decisão é crítica.

O app nunca depende diretamente do scraping.

A API atua como camada de controle, normalização e proteção.

Stack utilizada

Mobile

• Flutter

• Dart

• Riverpod (estado)

• Hive/SQLite (persistência)

Backend

• Python

• FastAPI

• HTTPX

• SQLite (inicial)

Scraping

• Selenium via cifraclub-api

• Docker

Infra

• DigitalOcean (Ubuntu)

• NGINX

• GitHub

Por que usar scraping nesse projeto?

Porque o objetivo aqui não é criar um produto final imediatamente.

É estudar:

• fluxo de dados real

• problemas de latência

• normalização de conteúdo

• fallback de erro

• arquitetura resiliente

O scraping entra como fonte de dados instável por definição, o que força o sistema a ser melhor desenhado.

O principal desafio técnico

Não é buscar a cifra.

É tratar a cifra.

O retorno vem em HTML, geralmente dentro de <pre>, com:

• alinhamento sensível

• acordes misturados com texto

• variações de notação

Isso exige:

• parsing consistente

• regex para identificação de acordes

• preservação de layout

• futura conversão para ChordPro

Transposição de acordes

Outro ponto importante do projeto é a lógica de transposição.

Base cromática:

C → C# → D → D# → E → F → F# → G → G# → A → A# → B

O sistema precisa:

• identificar acordes corretamente

• aplicar shift mantendo estrutura

• suportar variações como:

  • C#m7

  • G/B

  • F#7M

Isso parece simples, mas na prática exige testes bem definidos.

Roadmap técnico

O projeto foi estruturado em fases claras:

Fase 1 — Backend

• Endpoint /search mockado

• Contrato de API definido

• Testes com curl

Fase 2 — Integração

• Conexão com scraper

• Normalização de dados

• Tratamento de erro

Fase 3 — Flutter

• Tela de busca

• Tela de cifra

• Estados de loading e erro

Fase 4 — Evolução

• Cache local

• Favoritos offline

• Redução de dependência do scraping

Fase 5 — API própria

• Base estruturada

• Indexação

• Busca independente

Decisões técnicas relevantes

Alguns pontos importantes do projeto:

• API própria como camada obrigatória

• Separação entre dado bruto e dado normalizado

• uso de cache desde cedo

• contrato de API antes do app

• documentação antes do código

Inclusive, o projeto já nasce com:

• spec-kit (documentação técnica versionada)

• caveman (otimização de contexto para IA)

• design.md (padronização de UI/UX)

O que esse projeto resolve (de verdade)

Mais do que um app de cifras, esse projeto trabalha:

• integração entre frontend e backend

• consumo de dados não estruturados

• normalização e padronização

• arquitetura desacoplada

• preparação para escalar produto

Próximos passos

• Implementar backend mockado

• Validar contrato de API

• Integrar scraper via Docker

• Criar primeiros testes de parsing

• Iniciar Flutter apenas após estabilizar API

Conclusão

Projetos simples são bons para aprender sintaxe.

Projetos completos são os que realmente evoluem sua engenharia.

Esse aqui está no segundo grupo.

Se você trabalha com mobile, backend ou IA aplicada a produtos, esse tipo de abordagem faz diferença.

E esse é exatamente o objetivo.