Do primeiro lance ao apito final: uma aplicação Rails para acompanhar a Copa do Mundo de 2026.
Projeto de portfólio que combina integração com APIs esportivas, processamento em segundo plano e atualizações no navegador com Hotwire. Com a competição encerrada, o painel funciona como um acervo navegável: resultados das 104 partidas, as cinco melhores seleções e os cinco principais artilheiros.
Ruby on Rails 8.1 · PostgreSQL · Redis · Sidekiq · Hotwire · Bun · Tailwind CSS
Finalidade acadêmica: projeto de portfólio para estudar integrações HTTP, processamento assíncrono, consistência de dados e atualização de interfaces. Não é um serviço oficial dos organizadores ou dos provedores citados.
Problema e solução · Arquitetura · Desafios técnicos · Executar localmente · Testes
Acompanhar uma competição com fontes diferentes exige lidar com identificadores incompatíveis, indisponibilidade de APIs e reenvio de eventos. Executar toda a sincronização dentro de uma requisição também faz o usuário aguardar operações externas.
O HexaAlerts normaliza e persiste os dados no PostgreSQL, processa atualizações com Sidekiq e entrega mudanças ao navegador com Hotwire. Arquivos versionados permitem demonstrar o sistema sem credenciais de uma API paga e servem como alternativa durante falhas de integração.
O projeto contempla dois cenários: processamento de eventos e acompanhamento durante o torneio, e consulta ao acervo depois do encerramento. O estado atual prioriza essa retrospectiva; não há partidas ao vivo em andamento apenas por iniciar a aplicação.
- Retrospectiva do torneio: estado de competição encerrada, campeã em destaque e indicadores calculados a partir das partidas cadastradas.
- Rankings finais: top 5 seleções e top 5 artilheiros, com gols, assistências e links para as publicações oficiais da FIFA.
- Atualizar aplicação: um botão sincroniza seleções, calendário, placares, estatísticas e lances de todo o torneio em segundo plano. O painel informa o andamento e a última atualização, e se recarrega ao concluir via Turbo Streams.
- Acervo de partidas: filtros por grupos, mata-mata ou todos os jogos, incluindo final e disputa do terceiro lugar.
- Detalhes de cada jogo: placar, posse de bola, chutes, faltas, cartões, escanteios e lances registrados por jogador.
- Alertas personalizados: assinaturas por torcedor, seleção, partida e tipo de evento, com distribuição no navegador aos assinantes interessados. E-mail e push são propostas futuras.
- Webhooks autenticados: validação do contrato, comparação de token em tempo constante e processamento idempotente com Sidekiq.
- Demonstração reproduzível: seeds com as 48 seleções e as 104 partidas, sem depender da disponibilidade das APIs nem de uma chave paga.
- Interface responsiva: navegação em desktop e celular, foco de teclado visível e respeito à preferência por movimento reduzido.
flowchart TD
A["Botão de atualização ou webhook"] --> B["Controllers"]
B --> C["Jobs com Sidekiq e Redis"]
C --> D["Serviços de importação e processamento"]
E["APIs ou acervo local"] --> D
D --> F[("PostgreSQL")]
D --> G["Broadcasts após persistência"]
G --> H["Turbo Streams e Action Cable"]
H --> I["Painel e alertas no navegador"]
| Camada | Responsabilidade |
|---|---|
| Controllers | Receber requisições, validar entradas e iniciar operações. |
| Models | Associações, validações e integridade do domínio. |
| Services | Clientes HTTP, normalização, importação e reconciliação entre provedores. |
| Jobs | Processar eventos e executar sincronizações fora da requisição web. |
| PostgreSQL | Fonte de verdade, índices únicos e histórico de sincronizações. |
| Redis | Filas do Sidekiq e distribuição das mensagens do Action Cable. |
| Hotwire | Turbo Streams para atualizações e Stimulus para interações locais. |
A sincronização completa registra seu estado em CompetitionSync: na fila,
em execução, concluída ou falhou. Os detalhes indicam quantas partidas foram
importadas e se os dados vieram da API ou da cópia local. Uma falha mantém os
dados persistidos disponíveis e libera uma nova tentativa pelo botão.
| Tecnologia | Papel e decisão | Compromisso |
|---|---|---|
| Ruby 4.0.5 e Rails 8.1 | Integrar domínio, endpoints, persistência e views na mesma aplicação. | A execução depende de um ambiente Ruby compatível. |
| PostgreSQL | Persistir partidas, referências externas, eventos, assinaturas e sincronizações; impor restrições de unicidade. | Requer migrations e atenção aos limites das transações. |
| Sidekiq e Redis | Retirar sincronização e processamento da requisição web. | Exigem worker e Redis disponíveis, além de tratamento de falhas. |
| Turbo Streams e Action Cable | Atualizar o painel e distribuir alertas no navegador. | Dependem da conexão do cliente; transmissão não equivale a entrega durável. |
| Stimulus | Implementar interações locais no frontend. | Comportamentos permanecem associados às views Rails. |
| Bun e Tailwind CSS | Compilar JavaScript e CSS usados pelo Propshaft. | Os bundles precisam ser gerados em cada instalação. |
| Minitest e Selenium | Verificar regras, integrações simuladas e navegação. | Testes de navegador exigem Chrome. |
- Evento: o controller valida o token e o contrato, enfileira o job e responde ao provedor. O job localiza a partida, verifica duplicidade, grava o evento sob bloqueio e atualiza o estado. Depois da persistência, transmite as mudanças ao navegador.
- Atualização completa: o botão cria uma sincronização, enfileira o trabalho e permite continuar navegando. Os serviços consultam os provedores ou o acervo local; a operação registra origem, resultado ou falha.
- Consulta: páginas e filtros usam os dados persistidos. O seed permite preparar o acervo sem consultar as APIs.
-
Receber eventos repetidos sem duplicar gols ou notificações. Provedores podem reenviar o mesmo webhook. O identificador externo tem índice único, o job usa proteção contra concorrência e os testes verificam que o mesmo evento altera o placar uma única vez.
-
Reconciliar a mesma partida em provedores diferentes. Cada API usa identificadores próprios e pode informar horários diferentes. A importação combina equipes e uma janela de horário, mantém referências externas alternativas e reúne eventos e assinaturas na partida canônica.
-
Manter a aplicação demonstrável quando uma API sai do ar. Os clientes HTTP têm limites de tempo, tratam respostas inválidas e usam arquivos locais como alternativa. O seed carrega o torneio completo sem chamadas externas, e o painel identifica quando uma atualização usou a cópia local.
-
Atualizar todo o torneio sem bloquear a navegação. O botão enfileira um job no Sidekiq. O estado da operação fica no PostgreSQL, um índice único parcial impede atualizações simultâneas e o Turbo Streams atualiza o navegador ao término. Falhas ficam visíveis e permitem tentar novamente.
-
Transformar um painel ao vivo em um acervo coerente após a final. O painel passou a mostrar o encerramento, a campeã, os rankings finais e as fases eliminatórias. A sincronização consulta toda a temporada, importa partidas ausentes e interrompe o ciclo recorrente após o torneio. Probabilidades ao vivo não são exibidas em partidas encerradas.
-
Evitar a regressão de dados ao usar um calendário alternativo. A importação de arquivos locais preserva placares e estados já atualizados, mantém os dados detalhados de outros provedores e reaproveita os registros. Testes de importação cobrem idempotência e preservação dos resultados.
-
Garantir que o frontend funcione em uma instalação nova. JavaScript e CSS compilados não ficam no Git. O
bin/setupgera os bundles exigidos pelo Propshaft, e obin/devacompanha as alterações com Bun e Tailwind. O processo de instalação e a geração das capturas estão documentados.
| Decisão | Implementação | Verificação disponível |
|---|---|---|
| Processamento idempotente | ProcessMatchEventJob | Testes do job |
| Reconciliação de partidas | MatchDeduplicator | Testes de importação ESPN |
| Alternativa local quando um provedor falha | WorldCup2026::Refresh | Testes de atualização |
| Controle de sincronizações | Controller e job | Testes do controller |
| Distribuição por assinatura | MatchEventBroadcaster | Testes de assinaturas |
| Navegação e atualização da interface | Views, Turbo Streams e Stimulus | Testes de sistema |
O arquivo summary.json registra os rankings
finais conferidos em 17/10/2026, com os links de origem:
Os rankings são um registro histórico versionado. Não são inferidos de um conjunto parcial de eventos e não são recalculados pelo botão de atualização. A ordem da artilharia segue a publicação da FIFA, incluindo os desempates por assistências e menor tempo em campo.
O acervo espn_matches.json contém as
104 partidas, com data da captura e endereço da consulta de origem. O encerramento
da competição considera o calendário da edição, cuja final ocorreu em 19/07/2026.
| Fonte | Dados | Configuração |
|---|---|---|
| World Cup 2026 API | Seleções e calendário inicial | WORLD_CUP_API_URL, opcional. |
| ESPN Scoreboard | Resultados, fases, estatísticas e lances | ESPN_SCOREBOARD_URL, opcional. |
| football-data.org v4 | Fonte complementar de calendário e placares | FOOTBALL_DATA_API_TOKEN, opcional. |
| Arquivos locais | Demonstração e alternativa quando as APIs falham | Versionados em db/data/worldcup2026. |
A atualização completa consulta a temporada inteira na ESPN com limite de 200 registros, suficiente para as 104 partidas. Se a ESPN estiver indisponível, o sistema usa o acervo local e sinaliza essa origem no painel. A fonte secundária é consultada quando sua chave está configurada; sua indisponibilidade não impede a sincronização principal.
Comandos individuais continuam disponíveis:
bin/rails world_cup:sync
bin/rails espn:sync
# Opcional, com uma chave que tenha acesso à competição WC de 2026
FOOTBALL_DATA_API_TOKEN=sua-chave bin/rails football_data:syncDurante o torneio, a sincronização recorrente da ESPN usa intervalos de 30 segundos com jogos ao vivo e cinco minutos sem jogos ao vivo. Depois do fim da competição, o ciclo recorrente não é iniciado novamente; o acervo pode continuar sendo atualizado manualmente.
POST /api/v1/webhooks/match_events
Content-Type: application/json
X-Webhook-Token: dev-tokenExemplo para testar o fluxo de recebimento e processamento em segundo plano.
Use o identificador de uma partida cadastrada, disponível no console com
Match.first.external_id:
curl -X POST http://localhost:3000/api/v1/webhooks/match_events \
-H "Content-Type: application/json" \
-H "X-Webhook-Token: dev-token" \
-d '{
"event_id": "demo-event-001",
"match_id": "worldcup2026:1",
"type": "goal",
"team_code": "MEX",
"occurred_at": "2026-06-11T19:22:10Z",
"player": "Jogador de demonstração"
}'A simulação altera o placar local; rode a atualização completa para restaurar os
resultados históricos depois da demonstração. O endpoint responde 202 para um
payload válido, 401 para token inválido e 422 para dados fora do contrato.
Em desenvolvimento e teste, o token alternativo é dev-token. Em produção,
configure WEBHOOK_TOKEN.
- Ruby compatível com
.ruby-versione Bundler. - PostgreSQL em execução, com permissão para criar os bancos locais.
- Redis em execução.
- Bun para instalar as dependências e compilar JavaScript e CSS.
- Google Chrome para gerar as capturas de tela; não é necessário para subir o servidor.
# Instala dependências, compila assets e prepara o banco
bin/setup --skip-server
# Carrega as 48 seleções, 104 partidas e os lances do acervo local
bin/rails db:seed
# Em outro terminal, caso o Redis ainda não esteja em execução
redis-server
# Inicia Rails, JavaScript, CSS e Sidekiq
bin/devAcesse http://localhost:3000. Para usar outra porta:
PORT=3003 bin/devO botão Atualizar aplicação usa o worker Sidekiq iniciado pelo bin/dev.
Durante a sincronização, o botão fica indisponível e o banco impede que duas
atualizações sejam iniciadas ao mesmo tempo. Ao concluir, o painel é atualizado
sem exigir que o usuário recarregue a página.
Também é possível sincronizar diretamente pelo terminal, sem worker:
bin/rails competition:refreshOs seeds usam somente arquivos versionados. Reexecutá-los reaproveita as seleções, partidas e eventos existentes, sem apagar assinaturas de torcedores.
Os arquivos compilados de app/assets/builds não são versionados. O bin/setup
e o bin/dev preparam o frontend. Se optar por iniciar apenas bin/rails server,
gere os assets antes:
bun install
bun run build
bun run build:css
bin/rails serverIsso evita o erro The asset 'application.js' was not found in the load path.
| Variável | Finalidade | Quando configurar |
|---|---|---|
DATABASE_URL |
Conexão principal ao PostgreSQL. | Quando a conexão não utilizar a configuração local padrão. |
REDIS_URL |
Conexão Redis usada pelas filas e pelo Action Cable. | Para serviços Redis fora da configuração local padrão; em produção, definir a conexão. |
WEBHOOK_TOKEN |
Autenticar o recebimento de eventos. | Em produção; dev-token é apenas para desenvolvimento e teste. |
WORLD_CUP_API_URL |
Substituir o endereço do provedor inicial. | Opcional. |
ESPN_SCOREBOARD_URL |
Substituir o endereço do Scoreboard. | Opcional. |
FOOTBALL_DATA_API_TOKEN |
Habilitar a fonte complementar. | Opcional, com acesso à competição. |
PORT |
Alterar a porta usada no desenvolvimento. | Quando a porta padrão estiver ocupada. |
A arquitetura completa requer um processo web Rails, um worker Sidekiq, PostgreSQL e Redis. O ambiente de produção também precisa da configuração dos segredos Rails, assets e conexões de banco usadas em seu deploy. Esta seção não constitui um procedimento de implantação validado.
bin/rails test
bin/rails db:test:prepare test:system
bin/rubocop
bundle exec brakeman --no-pagerA suíte cobre o contrato e a autenticação do webhook, processamento idempotente, assinaturas, estatísticas, reconciliação de partidas, fallback do acervo completo, rankings, filtros, exclusão de atualizações simultâneas e estados de sucesso e falha da sincronização. APIs são substituídas por clientes de teste para que a suíte não dependa de rede ou credenciais.
Os testes de sistema usam Chrome em modo headless e cobrem rankings, navegação entre fases e detalhes das partidas, criação e remoção de alertas, layout no celular e atualização automática do painel após a execução do job. Os serviços externos são substituídos durante o teste da sincronização; Redis e Sidekiq não precisam estar em execução para rodar a suíte.
O repositório inclui workflow de CI com análise estática, auditoria de dependências, lint e testes. A existência do workflow não informa o resultado da última execução; consulte o GitHub Actions para verificar o estado atual. Não são apresentadas métricas de cobertura, carga ou latência sem medição.
- Autenticação de torcedores e autorização de operações administrativas ainda aparecem no roadmap; o estado atual deve ser tratado como demonstração.
- Alertas são transmitidos no navegador. Entrega por e-mail ou push ainda não está implementada.
- Persistência de um evento e transmissão ao navegador são operações separadas. Se o broadcast falhar após a gravação, repetir o evento não garante reenviar a notificação, pois a proteção de duplicidade impede novo processamento.
- O acervo local mantém a demonstração disponível, mas não garante a atualização dos dados externos.
- A identidade canônica das partidas depende das regras de reconciliação e dos dados recebidos dos provedores.
- Rankings finais são snapshots versionados; o botão de atualização não os recalcula.
- Não há resultados de benchmark que comprovem capacidade de processamento ou latência de entrega.
Propostas de evolução, ainda não apresentadas como funcionalidades concluídas:
- Autenticação de torcedores e autorização para operações administrativas.
- Controle durável da entrega de notificações, avaliando outbox e retentativas independentes da gravação do evento.
- Preferências por canal de entrega, como e-mail e push.
- Métricas de latência, falhas, origem dos dados e painel de observabilidade.
- Testes de falha entre persistência e broadcast, com verificação da recuperação.
- Adaptar o domínio para outras competições e edições.
- Documentar e validar a implantação completa dos processos web e worker.
As imagens deste repositório são capturas reais da aplicação executando localmente, com os dados históricos carregados pelo seed.
Para gerar novamente as imagens, inicie a aplicação, carregue os seeds e execute:
SCREENSHOT_BASE_URL=http://localhost:3000 bin/screenshotsO script usa Chrome em modo headless via Selenium, salva as três imagens em
docs/screenshots e verifica se há transbordamento horizontal no celular.



