The World Cup is on, half my feed is football, and I wanted an excuse to build something. So I built Kickoff Cards: upload a selfie, pick your nation, and you become a playable football trading card that you battle other people's cards with to earn XP and climb a live leaderboard.
The game
The idea is simple: you turn yourself into a football trading card. Think of a Panini sticker or a FIFA Ultimate Team card, except the player on it is you.
You upload a selfie and pick a nation, and a few seconds later you get a card back: your face cut out and dropped into the frame in your nation's colours, with six stats down the side (pace, shooting, passing, and so on) that decide how it performs. There's no signup to get this far; you get an anonymous session on first load and the card belongs to you. Anything you upload is run through automated moderation before it appears in the public gallery.
Then you play it. You send your card into the battle arena, it's matched against another player's, and the two go head to head across those six stats. Winning earns XP, enough XP levels the card up, and a level-up nudges its stats and regenerates the card image to match. A leaderboard tracks who's ahead and updates in real time as battles resolve.
That's the whole loop: make a card, fight with it, level it up, climb the board. It's small, but it touches most of what a real user-media app has to deal with: uploads, AI image processing, moderation, live state, and public content.
The card game is the demo. What this post really focuses on is how the four tools it's built on fit together.
I deliberately chose tooling that works well with agentic development environments: current, trustworthy docs and MCP servers that let the agent check its work against the real project rather than guess from training data. Next.js, Cloudinary, Supabase and Vercel are leaders in this field, and that's a fair part of why this came together quickly. More on that later.
The split is clean: Next.js owns the app, Cloudinary owns media, Supabase owns data, and Vercel ships it, each handing off to the others through stable APIs. It's open source, runs entirely on free tiers. You can play it at kickoff-cards.vercel.app, and the code for you to fork and run yourself: github.com/cloudinary-devs/kickoff-cards
Here's the whole flow on one diagram:
Browser
│
├─ GET page ──→ Next.js Server Component ──→ Supabase (RLS)
│ └─→ Cloudinary URL builder
│
├─ POST /api/sign-upload ──→ signed upload params
│
└─ Direct upload ─────────→ Cloudinary
│
Async moderation
│
Webhook ──→ Supabase update ──→ Realtime ──→ Browser
The rest of this post walks through the decisions behind that diagram.
Why not just store the files?
The first decision was what to do with the uploaded photos. The easy version is: save the file, serve it back, done. That holds up until you actually look at what a card needs: background removal, a face-aware crop, compositing onto the template, text overlays, modern formats, and moderation on anything a stranger uploads. Do it yourself and you're suddenly maintaining a transform pipeline, a CDN, and a moderation step.
I didn't want to build that, so the image work goes to Cloudinary: I describe the transformation I want, get a URL back, and it generates and caches the result on first request. The useful side effect is that a finished card ends up being a single URL with no server-side rendering, which I'll come back to.
Uploads that never touch my server
A lot of upload flows go browser → your server → storage, which means your server parses multipart bodies, buffers files, and streams them back out. Kickoff Cards skips that: the server signs a set of upload parameters, hands them to the browser, and the browser uploads straight to Cloudinary. The only thing my code produces is a signature.
export function getSignedUploadParams({ userId, kind }) {
const timestamp = Math.round(Date.now() / 1000)
const publicId =
kind === "avatar"
? `kickoff/users/${userId}/avatar`
: `kickoff/users/${userId}/uploads/${crypto.randomUUID()}`
const signature = cloudinary.utils.api_sign_request(
{ timestamp, public_id: publicId, overwrite, moderation, notification_url },
env.CLOUDINARY_API_SECRET,
)
return { signature, timestamp, apiKey, cloudName, publicId }
}
Because the signature covers every parameter, the client can't change the destination path, the moderation settings, the webhook URL, or the overwrite behaviour without invalidating it. You get direct uploads while the server keeps control of where files land.
This is deliberately not an upload preset. Presets work for static config, but they aren't user-aware: they can't carry the authenticated user's ID, a per-request destination, or a dynamic webhook. That gets generated server-side and signed; the browser submits it.
Sessions without signup
That userId in the upload path comes from Supabase. There's no login: Supabase Anonymous Auth gives each visitor a real authenticated session on first load, backed by a cookie and a stable user ID, and their cards, battles, and XP all hang off that ID. Uploads are scoped to it (kickoff/users/{userId}/...), so a card belongs to the right person without any extra plumbing.
It's a reasonable fit for a low-friction demo, and it isn't a dead end: if I later add OAuth or magic links, anonymous is just another provider and the data model doesn't change.
A whole trading card is one URL
The finished card (background removed, face cropped into the window, six stats printed at set coordinates, watermark on the bottom) isn't rendered on a server. No canvas, no image endpoint, nothing written to disk. It's a single Cloudinary URL.
const transformation = [
{ overlay: layerId },
{ effect: "background_removal" },
{ crop: "fill", gravity: "face", width: tmpl.photo.w, height: tmpl.photo.h },
{ flags: "layer_apply", gravity: tmpl.photo.gravity, x: tmpl.photo.x, y: tmpl.photo.y },
// six stat overlays, one per attribute
...STAT_ATTRS.flatMap((attr) => [
{ overlay: { font_family: "Arial", font_size: 44, font_weight: "bold", text: String(stats[attr]) }, color: "black" },
{ flags: "layer_apply", gravity: "north", x: slot.x, y: slot.y },
]),
{ overlay: "kickoff:cloudinary-logo", width: 220, crop: "scale", opacity: 55 },
{ flags: "layer_apply", gravity: "south", y: 28 },
{ width: 800, crop: "limit" },
]
return cloudinary.url(`templates/${nation}`, {
transformation,
fetch_format: "auto",
quality: "auto",
secure: true,
})
Cloudinary runs that chain the first time the URL is requested, caches the result, and serves subsequent requests from the CDN. There's no image-processing server to run.
A few things to watch for:
- Order matters. Background removal has to come before the crop. Flip them and Cloudinary crops the original first, then removes the background from that rectangle, which gives a worse result.
-
gravity: "face"matters. Without it, a full-body selfie tends to crop to the chest rather than the face. -
Layer IDs use colons, not slashes.
kickoff/users/abc/uploads/xyzbecomeskickoff:users:abc:uploads:xyz. Small detail, easy to miss when debugging transformation URLs. - Cache busting is automatic. When a player levels up, I rebuild the URL with the new stats. A different URL is a different cache key, so Cloudinary renders the updated card on the next request, with no purge calls or CDN management.
Every browser-facing image ends with fetch_format: "auto" and quality: "auto", so Cloudinary serves WebP/AVIF where supported and picks a compression level, usually smaller files with no extra config.
One deliberate non-choice: I'm not using next-cloudinary. The card URLs are already complete transformation URLs stored in the database. Plain next/image with unoptimized handles layout, sizing, and lazy-loading, while Cloudinary stays responsible for the media. That's one fewer abstraction between the app and the transformation pipeline.
Moderation on upload
If you accept user images, you need moderation, because some fraction of "selfies" won't be selfies. The DIY version is a vision API plus a queue, retries, and another set of credentials. Cloudinary handles it as part of the upload instead.
Every signed upload carries an AWS Rekognition moderation string:
aws_rek:explicit_nudity:0.4:suggestive:0.4:violence:0.4
After the upload, Cloudinary runs moderation asynchronously and POSTs the verdict to my webhook, which verifies the signature, reads the status, updates the row in Supabase, and deletes anything rejected. The user watches their card flip from Pending to Approved (or get bounced) without refreshing, because that database write feeds a Realtime subscription. That's where Supabase comes in.
Supabase: the right key for the right job
I use three Supabase clients on purpose, and keeping them separate avoids a common class of security bug.
| Client | Key | Job |
|---|---|---|
lib/supabase/server.ts |
Anon | Server Components, Route Handlers, Server Actions (RLS enforced) |
lib/supabase/client.ts |
Anon | Browser Realtime subscriptions only |
lib/supabase/admin.ts |
Service role | Webhooks and privileged server work (bypasses RLS) |
The service-role key bypasses Row Level Security, so it lives in one server-only module. If it's accidentally imported into client code, the build fails rather than leaking the key. Two places use it intentionally: the moderation webhook you just saw (which has to delete any card) and battle resolution (the battles table has WITH CHECK (false) on insert, so results can't be written from the client). Everything else runs under normal RLS, which is easier to reason about than one client that's sometimes an admin and sometimes not.
Live updates without polling
Two bits of UI update live: the leaderboard and moderation status. Both use the same pattern: subscribe to a table and let Postgres changes push to the client.
const channel = supabase
.channel("leaderboard")
.on("postgres_changes", { event: "*", schema: "public", table: "profiles" }, () => {
router.refresh()
})
.subscribe()
When a battle changes someone's XP, the leaderboard re-renders. When Cloudinary's webhook updates a card, the card page reacts. No polling and no WebSocket server to run yourself:
External service → Webhook → Postgres → Supabase Realtime → Browser
The same shape works for other async work: payments, AI jobs, background processing.
Building this with an agent
Here's the "more on that" from the intro. The reason the stack choice mattered is that all three of Cloudinary, Supabase and Vercel expose MCP servers, so the agent can query the actual project rather than rely on training data. It can browse uploaded assets and test a transformation in Cloudinary, check the live schema and RLS policies in Supabase, and read deployment logs in Vercel. For a media-heavy app that's the difference between the agent guessing and the agent checking: instead of hardcoding a URL and refreshing a tab to see if a transformation worked, it verifies the result directly.
The repo supports this with an AGENTS.md (architecture rules, conventions, and which dependencies move fast enough that it should fetch current docs) and vendored skills under .agents/skills/ for Supabase and Postgres, so it works from current guidance when writing migrations.
Nothing here is agent-specific, really. The same things that make the codebase easy for an agent to work in (clear boundaries, one place per concern, services it can query directly) are what make it easy for a person. The agent just makes it obvious when you've got those wrong.
Run it
git clone https://github.com/cloudinary-devs/kickoff-cards
cd kickoff-cards
pnpm install
cp .env.example .env.local
pnpm dev
You'll need a free Cloudinary account with the AWS Rekognition add-on enabled (the free quota is plenty), a Supabase project with anonymous auth on, and the schema from supabase/schema.sql. For local webhook testing, a Cloudflare tunnel does the job without an account:
cloudflared tunnel --url http://localhost:3000
# paste the HTTPS URL into CLOUDINARY_WEBHOOK_URL
Full walkthrough is in docs/getting-started.md.
What carries over
Aside from the football, these are the patterns that apply to most apps handling user media:
Signed direct uploads. The browser uploads to Cloudinary, the server only signs. The file never passes through your app.
One transformation builder. Keep the transform logic in a single function rather than scattered across components.
Separate Supabase clients. Anon, browser, and service-role as distinct responsibilities, so RLS isn't bypassed by accident.
Webhook + Realtime. External service → webhook → database → Realtime → browser. No polling, and it generalises to moderation, payments, and background jobs.
None of these are specific to a card game, or to this stack. They're just what fell out of giving each service one clear job and letting it do it.
If you want to poke at the code, most of it lives in lib/cloudinary/ and lib/supabase/. It's MIT-licensed, so take what's useful.
| Cloudinary ❤️ developers |
|---|
| Ready to level up your media workflow? Start using Cloudinary for free and build better visual experiences today. |
| 👉 Create your free account |
Top comments (0)