Padelo

Padelo is a web app for running Americano and Mexicano padel tournaments. It generates rounds, opens a shared live room, tracks match scores, keeps the leaderboard current, and lets players follow from a link or QR code.

Production site: padelo.fun

Features

• Americano and Mexicano tournament setup.
• Fixed-round or open-ended sessions.
• Room codes, shared URLs, and QR-friendly tournament rooms.
• Live score updates with server-sent events.
• Score validation against the configured target score.
• Optimistic concurrency checks for multi-device score entry.
• Player leaderboard, match history, tournament logs, and finished results pages.
• "Play again" flow that reuses a finished tournament's settings.
• Recent rooms saved locally in the browser.

Stack

• Frontend: Vite, React, TypeScript, Tailwind CSS, shadcn/ui-style components.
• Backend: Hono, TypeScript, Node.js.
• Database: PostgreSQL with Drizzle migrations.
• Realtime: server-sent events.
• Deployment: Docker Compose behind Cloudflare Tunnel.

App Routes

Route	Purpose
/	Home page and recent rooms
/new	Create a tournament
/t/:roomCode	Live tournament room
/t/:roomCode/done	Finished tournament results

Local Development

This repo has separate frontend and backend packages, not a root workspace. Install dependencies in each package.

Prerequisites:

• Node.js 22 or compatible.
• pnpm 10.18.1, preferably via Corepack.
• PostgreSQL running on this host. Use a shared local Postgres service for dev apps, with one database and role per app.

Create the local app database once:

createuser --login --pwprompt padelo
createdb --owner=padelo padelo

Use padelo as the local role password, or update backend/.env after copying the example.

Run the backend:

cd backend
pnpm install
cp .env.example .env
pnpm db:migrate
pnpm run dev

Run the frontend in another terminal:

cd frontend
pnpm install
pnpm dev

Open http://localhost:5173. The Vite dev server proxies /api requests to the backend at http://localhost:8123.

Backend health check:

curl http://localhost:8123/health

Useful Commands

Backend:

cd backend
pnpm test
pnpm typecheck
pnpm build
pnpm db:generate
pnpm db:migrate

Frontend:

cd frontend
pnpm test
pnpm typecheck
pnpm build
pnpm preview

Documentation

• API
• Docker deployment
• Feature notes
• GitHub repo copy

Environment

Root .env values are used by Docker Compose. Start from .env.example and set DATABASE_URL to the production database connection string. In production, the backend joins the main-timescaledb Docker network, so the database host should be the TimescaleDB container's DNS name on that network.

backend/.env is for local backend development. Its example points at the shared host-level Postgres service on localhost:5432.

Deployment

See docs/DOCKER.md for the production Compose flow, expected Cloudflare Tunnel network, and request body limit notes.