Mundial de Clicks is an open-source real-time web app where users click to vote for their national team. Every click is a vote, the global ranking updates live via Server-Sent Events, and the infrastructure is built to survive internet-scale traffic spikes — atomic DragonFly counters, a single Lua script per vote batch, and one global polling loop that scales to thousands of simultaneous viewers.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/midudev/mundial-de-clicks/llms.txt
Use this file to discover all available pages before exploring further.
Quickstart
Run the app locally in three commands — no configuration required.
Architecture
Understand how votes flow from click to DragonFly to every viewer’s screen.
Deploy on Coolify
Step-by-step guide to deploying the full stack on a VPS with Coolify.
API Reference
Explore every endpoint: vote, ranking, SSE stream, captcha, health, and status.
How it works
Mundial de Clicks is engineered to absorb massive click bursts without falling over. The core trick is that no row is written per click:User clicks a flag
The browser accumulates clicks for 400 ms and sends them as a single batched request — up to 10 votes across 3 countries at once. The UI updates instantly (optimistic state).
Atomic Lua script runs in DragonFly
A single Lua script validates the captcha session, applies rate limiting, writes
ZINCRBY on the ranking sorted set, and increments the per-second CPM bucket — all in one round-trip, zero race conditions.One poller serializes the world
A single
setInterval loop reads DragonFly once per tick, detects overtakes and milestones, serializes the snapshot to bytes once, and fans it out to every connected SSE subscriber. 1 viewer or 50,000 — same cost.Key features
Atomic vote processing
One Lua script handles rate limiting, session validation, and vote writing in a single DragonFly round-trip.
Global SSE broadcast
One serialization per tick, shared across all viewers. Viewer count doesn’t affect DragonFly load.
Cap PoW captcha
Proof-of-work anti-bot protection with progressive difficulty that scales with daily vote count per IP.
In-memory fallback
Works without DragonFly configured — votes run in-process memory so you can develop locally instantly.
Daily vote limits
Per-IP and per-signed-cookie daily caps enforced atomically inside the same Lua script.
Coolify deployment
Three services (app + DragonFly + Umami) wired together with environment variables — no code changes needed.
Explore the documentation
Environment Variables
Every configuration knob with defaults and production recommendations.
Anti-Abuse Guide
How rate limiting, daily caps, and captcha work together to stop bots.
Analytics Setup
Add Umami analytics to track real-time user engagement.