Arquitetura — Varzea Fest

🎯 Visão Geral

Varzea Fest é uma plataforma completa para gestão de festivais de futebol de várzea. Promotores criam eventos, técnicos inscrevem equipes, jogadores se vinculam a times, e todo o ciclo — inscrição, emparelhamento de jogos, registro de resultados e classificação — é gerenciado online.

Ruby 3.3.8 Rails 8.1.3 PostgreSQL 16 Redis 7 Sidekiq 8 Hotwire Docker RSpec

⚡ Stack Tecnológica

Camada	Tecnologia
Linguagem	Ruby 3.3.8
Framework	Ruby on Rails 8.1.3
Database	PostgreSQL 16 (Alpine)
Cache / Jobs	Redis 7 + Sidekiq 8
Frontend	Hotwire (Turbo + Stimulus) + Propshaft
Autenticação	bcrypt (session) + JWT (API)
Container	Docker + Podman
Orquestração	Docker Compose
Testes	RSpec 7 + FactoryBot + Shoulda Matchers
Qualidade	RuboCop, Brakeman, Bundler Audit

🗄️ Modelagem de Dados

8 modelos ActiveRecord com PostgreSQL, utilizando STI (Single Table Inheritance) para usuários e enum para status.

User (STI)

Promotor · Técnico · Jogador

Evento

rascunho → aberto → fechado → encerrado

Jogo

2 rodadas · chave vencedores/perdedores

TokenConvite

convite_tecnico · convite_jogador

Inscrição

Equipe + Jogador · status + pagamento

Passaporte + AuditLog

Vinculação + Auditoria

🛣️ Rotas Principais

Frontend Web (Hotwire)

/ — Home
/eventos — Lista pública
/eventos/:id — Detalhe do evento
/convite/:codigo — Página de convite
/painel/promotor — Dashboard promotor
/painel/tecnico — Dashboard técnico
/painel/jogador — Dashboard jogador

API REST (JSON)

POST /api/v1/users/sign_in
GET /api/v1/eventos
POST /api/v1/eventos/:id/inscricoes/equipe
POST /api/v1/equipes/:id/tokens/jogador
GET /api/v1/tokens/:codigo/validar
PATCH /jogos/:id/placar

🔄 Fluxo de Usuário

Visitante

▼

Promotor

Técnico

Jogador

▼

Inscrição Confirmada

▼

Gerar Jogos (R1 + R2)

▼

Registrar Placar

▼

Classificação / Ranking

📊 Estados do Evento

Rascunho Aberto Fechado Encerrado

Transição	Destino	Ações
`abrir!`	aberto	Vincula passaportes premium
`fechar!`	fechado	—
`encerrar!`	encerrado	—
`reabrir!`	aberto	Volta de fechado

⚙️ Services

Service	Responsabilidade
`GeradorJogos`	Emparelhamentos R1 (sorteio) + R2 (vencedores × vencedores / perdedores × perdedores)
`CalculadorClassificacao`	Pontos, saldo de gols, ordenação das equipes
`TokenService`	Geração e envio de tokens de convite
`PassportService`	Vinculação automática de passaportes premium
`JwtService`	Codificação/decodificação de JSON Web Tokens

🔐 Autenticação e Autorização

Web (Session/Cookie)

Login email + senha (bcrypt)
Sessão por session_token
Painéis por tipo de usuário

API (JWT)

Bearer token com expiração
Blacklist de tokens
Rate limiting integrado

Perfil	Permissões
Promotor	Eventos, tokens, jogos, placares
Técnico	Equipe, inscrições, convites jogador
Jogador	Usar token, vincular-se
Admin	Visão global, bloqueio, auditoria

🛡️ Segurança

✅ Senhas com bcrypt
✅ Confirmação de email (6 dígitos)
✅ Bloqueio de conta
✅ Forçar logout via session_token

✅ Rate limiting na API
✅ CORS configurado
✅ AuditLog para ações críticas
✅ Apenas promotor altera placar

📧 Background Jobs (Sidekiq)

Job	Disparo	Ação
`EmailConfirmacaoJob`	Cadastro	Código de confirmação
`EmailTokenTecnicoJob`	Token técnico	Convite ao técnico
`EmailTokenJogadorJob`	Token jogador	Convite ao jogador
`EmailPassaporteJob`	Vinculação	Notifica passaporte

🐳 Infraestrutura

Serviços Docker

web (Puma :3000)
sidekiq (jobs)
PostgreSQL 16
Redis 7

Rede

varzea_net (interna)
auth_serv_net (auth externo)
Domínio: varzeafest.duckdns.org

📝 Histórico de Commits

a9fdb0c docs: adiciona documentação de arquitetura do projeto

e5e6885 feat: melhora layout do card de jogos com grid centralizado e adiciona botao reabrir no promotor

1788799 feat: adiciona tabela de jogos, classificação e melhorias no frontend cyberpunk

2c42985 feat: apply cyberpunk 2077 theme to Varzea Fest

c2df648 feat: initial commit - Varzea Fest (Podman stack)