Tico Games
Read in English
Aplicación web (PWA) para quinielas de fútbol entre amigos: cada grupo predice
los marcadores de un torneo, la app puntúa sola con los resultados reales y
lleva la tabla, el histórico y el pozo.
Nació para el Mundial 2026 y hoy corre varios torneos a la vez — Copa del
Mundo, UEFA Champions League y la primera división de Costa Rica— cada uno con
sus propias quinielas, reglas y puntajes.
La usa un grupo real de 26 personas, y se juega por plata. Eso condiciona casi
todas las decisiones de diseño: nadie puede ver las predicciones ajenas antes
del saque, las reglas no se cambian con el torneo en marcha sin votación del
grupo, y un puntaje mal calculado no es un detalle cosmético.
Qué hace
- Predicciones con cierre automático 15 minutos antes de cada saque. Hasta
ese momento, nadie ve lo que predijeron los demás.
- Puntaje automático: marcador exacto, resultado correcto, reglas propias
para las tandas de penales, y un comodín «×2» con cupo por ronda.
- Marcadores en vivo sincronizados desde ESPN, con la tabla y el histórico
recalculándose solos.
- Detalle del partido: alineaciones dibujadas sobre una cancha, forma
reciente de los dos equipos y enfrentamientos previos.
- Avisos: resumen de los partidos del día a las 6 a.m. y recordatorio 45
minutos antes del saque, solo a quien tiene predicciones pendientes.
- Varias quinielas por torneo, cada una con su admin, sus reglas de puntaje,
su pozo y sus votaciones para cambiar las reglas.
Stack
| Capa | Tecnología |
|---|
| Frontend | React 19 · Vite 6 · Tailwind CSS 4 · motion · TanStack Query · vite-plugin-pwa |
| Backend | FastAPI (Python 3.12) · PyJWT · httpx · pywebpush |
| Base de datos | PostgreSQL en Supabase, con Row Level Security y pg_cron |
| Autenticación | Supabase Auth: correo y contraseña, o «Entrar con Google» |
| Despliegue | Vercel (frontend y backend juntos) |
Estructura
frontend/ React + Vite. La PWA y toda la interfaz.
backend/ FastAPI. Sincronización con ESPN, notificaciones push, tareas de admin.
database/ Migraciones SQL numeradas (87 a la fecha). Se aplican a mano.
docs/ Documentación de funcionalidades concretas.
shared/ Constantes compartidas.
scripts/ Utilidades sueltas de mantenimiento.
Correrlo en local
Hace falta Node 20 y Python 3.12, y un proyecto de Supabase propio con
las migraciones de database/ aplicadas en orden.
Frontend
cd frontend
npm install
cp .env.example .env # y completá los valores de tu proyecto
npm run dev # http://localhost:5173
.env necesita:
VITE_SUPABASE_URL=https://<tu-proyecto>.supabase.co
VITE_SUPABASE_ANON_KEY=<tu anon key>
VITE_API_URL=/_backend
Backend
cd backend
python -m venv .venv && source .venv/bin/activate
pip install -r requirements-dev.txt
cp .env.example .env # y completá los valores
uvicorn app.main:app --reload # http://localhost:8000
requirements.txt es solo lo que viaja al serverless;
requirements-dev.txt lo incluye y añade el servidor local y pytest.
Pruebas
cd frontend
npm test # 301 pruebas de lógica (vitest)
npm run test:ui # 150 pruebas de interfaz (Playwright, sin backend real)
npm run lint
cd ../backend
python -m pytest # 212 pruebas
Las de Playwright interceptan Supabase: no tocan ninguna base de datos real
y no necesitan credenciales.
Despliegue
Cada push a main despliega frontend y backend juntos en Vercel
(vercel.json → experimentalServices; el backend queda bajo /_backend).
Las tareas periódicas —sincronizar marcadores, el resumen de las 6 a.m. y el
recordatorio del saque— las dispara pg_cron desde la propia base de datos,
no GitHub Actions. Se midió que schedule: de GitHub cumplía apenas el 2.5% de
las corridas esperadas.
Las migraciones de database/ se aplican a mano en el editor SQL de
Supabase, en orden. database/verificar_estado.sql es de solo lectura y compara
la base viva contra el repo.
Documentación
CLAUDE.md — el documento importante: un registro de
decisiones de arquitectura con la medición que motivó cada una, el modo de
fallo que evita y los errores que ya se cometieron. Si vas a tocar el puntaje,
la seguridad de la base o los cupos del comodín, empezá por ahí.docs/CALENDARIO.md — exportación de partidos al calendario.APLICAR_MIGRACIONES.md — cómo aplicar las migraciones.
Estado
En producción y en uso. No es un proyecto de demostración: los datos son reales
y hay dinero de por medio, así que los cambios se miden antes de publicarse.
