DEV Community: Nick Bradley

Building a World Cup card battler that turns your selfie into a football card (Next.js, Cloudinary, Supabase, Vercel)

Nick Bradley — Tue, 14 Jul 2026 21:44:56 +0000

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/xyz becomes kickoff: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

Your model returns a file. Production needs an asset.

Nick Bradley — Mon, 06 Jul 2026 13:40:43 +0000

Your agent calls an AI image or video model (OpenAI, Google, Runway, fal) and, a few seconds later, gets back a URL or a blob of base64. Feels like the job is done. It isn't. That raw output will probably expire, it's the wrong size and format for wherever it's headed, it carries no record of what made it, and nobody has checked it against your brand. And because it's an agent, there's no human standing by to fix any of that.

The disappearing URL gets all the attention, but it's only the first of several steps between "the model responded" and "I can ship this." Here's the whole path.

What this covers: what happens when generated media expires across the major APIs, what "production-ready" actually requires (persist, transform, deliver, brand, find), and how to collapse that pipeline into one step.

Step zero: the output is built to disappear

Generated media is ephemeral by default, and the details vary more than you'd expect:

OpenAI: image models like gpt-image-2 return base64 bytes, no hosted URL at all, so you own storage from the first response. Sora video files last ~48 hours (download URLs ~1 hour), and the Sora video API is being sunset in September 2026.
Google: the current image models, Nano Banana 2 (Gemini 3.1 Flash Image) and Nano Banana Pro (Gemini 3 Pro Image), return bytes inline through the Gemini API. For video, Veo 3.1 output is kept two days behind the Files API, then deleted.
Runway: Gen-4 image and video output URLs expire in roughly 24–48 hours; the docs tell you plainly to download and self-host.

This isn't a bug. These are inference platforms, not asset hosts, and serving files forever is expensive. The trap is that "save it before it vanishes" quietly became your job, and most teams only find out when a link 404s in production.

Persistence alone isn't the finish line

The landscape is shifting, to be fair. fal.ai now offers fal Assets, where generations persist instead of expiring, and platforms like Leonardo keep outputs indefinitely. Even routing layers like OpenRouter's Unified Image API give you one endpoint across dozens of models, though as a router it stores nothing, so persistence is still yours to solve.

But solving expiry only solves step zero. A file that lives forever in one vendor's library is still unoptimised, unbranded, scattered across whichever providers you happen to use, and only as findable as that vendor's UI. The hard part was never just keeping the bytes.

Why autonomous agents make media persistence harder

When a person generates an image in a web UI, they're right there to download it, crop it, eyeball the brand, and drop it where it belongs. Agentic workflows delete that entire safety net.

An agent runs in the background. It calls a model, gets a result, and moves on: the output lands in a state object or a database row, and nobody looks until much later. Good agent-state design even says to store large artifacts as files and keep only the path in state. Sound advice, but it assumes the file is somewhere permanent and usable. A raw model URL is neither. So every step a human would have done by hand now has to happen automatically, at generation time. That's the actual job.

What "production-ready" actually means

Strip it back to what has to be true before generated media can ship:

Persisted: captured the instant it's created, so nothing depends on an expiring URL.
Optimised & transformed: the right format and size for each destination. A 4 MB PNG becomes a 40 KB WebP thumbnail, a social crop, an AVIF for modern browsers. Video is harder: transcoding to MP4/WebM, an adaptive HLS/DASH stream, a poster frame, often a trimmed cut, all from one master.
Delivered: served fast from a CDN, video streamed adaptively rather than shipped whole from one region.
On-brand: checked against brand rules before a customer sees it. An agent generating customer-facing media with no brand guardrail is a real risk, not a hypothetical.
Findable: stored with its metadata: prompt, model, use-case, tags, and for video things like duration and captions. An agent that can't search its own output regenerates the same thing twice.

Miss any one of these and you don't have an asset; you have a raw output and a to-do list.

This is really an asset pipeline

Every one of those requirements already exists in traditional media workflows. AI generation hasn't removed the pipeline, it has simply automated the first step. Agents make that more obvious because there's no human left to bridge the gap manually.

Building the media pipeline yourself

The pattern everyone reaches for looks simple:

generate → download the bytes → push to your object store → serve from there

The store is usually S3, Cloudflare R2, or Supabase, and the mechanics are well-trodden. But persisting the bytes is the easy ~60%. What's left on your plate:

Glue code on every generation path, with retries for when the URL expires mid-download (worse for large video files).
A transformation service (Lambda + sharp, imgix) and, for video, a transcoding pipeline (FFmpeg or managed) for streamable renditions and poster frames.
A CDN in front, with adaptive streaming for video.
A brand check, which most pipelines just skip.
A metadata store you build and maintain so assets stay findable.

You can absolutely assemble this, and if storage cost dominates and your transform needs are light, R2-plus-a-Worker is a sensible call. Just be honest that you're now operating a small media pipeline, not a bucket.

Two pipelines, one call

The model step is identical either way. What differs is everything after it.

The generation call below is deliberately abstracted: whether generateMedia() wraps OpenAI, Google, Runway, fal, or an OpenRouter route, you're left holding the same thing: an ephemeral URL you now have to productionise.

The DIY way: download, race the expiry, persist, then start the rest of the pipeline.

import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";
const s3 = new S3Client({ region: process.env.AWS_REGION });

const modelOutputUrl = await generateMedia(prompt); // any provider; ephemeral

const res = await fetch(modelOutputUrl);            // race the clock
if (!res.ok) throw new Error(`Model URL expired: ${res.status}`);
const bytes = Buffer.from(await res.arrayBuffer());

await s3.send(new PutObjectCommand({
  Bucket: process.env.S3_BUCKET,
  Key: `generations/${Date.now()}.png`,
  Body: bytes,
  ContentType: "image/png",
}));

// Still TODO, separately: transform/transcode, CDN, brand check, metadata store…

The pluggable way: hand the same URL to a media pipeline and get a production asset back in one call. (This example uses Cloudinary, but the shape is what matters.)

import { v2 as cloudinary } from "cloudinary"; // configured from CLOUDINARY_URL

const asset = await cloudinary.uploader.upload(await generateMedia(prompt), {
  folder: "agent-generations",
  context: { prompt, model: modelName },            // searchable metadata
  eager: [{ width: 400, height: 400, crop: "fill",
            fetch_format: "auto", quality: "auto" }], // optimised derivative
});

asset.secure_url;          // permanent original, CDN-delivered
asset.eager[0].secure_url; // optimised WebP thumbnail

It fetches the bytes (no expiry race in your code), stores a permanent original, derives renditions on demand, and tags it with its metadata. Pass resource_type: "video" and the eager transforms become an adaptive stream and a poster frame instead of image crops. Same call for an image from one provider or a clip from another, and the agent ends up holding one stable, branded, findable URL, no per-model recipe required.

Or generate straight into your asset platform

If the generator and the asset platform are the same system, there's no ephemeral URL to rescue in the first place. That's the idea behind Cloudinary's new Image Generation API: a single text_to_image endpoint across best-in-class model families (FLUX.2, Nano Banana, GPT Image, Recraft, Ideogram), much like the routing layer from earlier, except the output lands as a managed asset rather than a disappearing link.

curl -X POST https://api.cloudinary.com/v2/generate/<CLOUD_NAME>/text_to_image \
  -u "<API_KEY>:<API_SECRET>" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "a golden retriever wearing a tiny astronaut helmet",
    "model":  { "family": "flux", "tier": "premium" },
    "target": { "target_type": "managed_asset" }
  }'

The response is a permanent secure_url plus the asset_id and public_id you use everywhere else in Cloudinary. The image is born persisted, optimisable, and ready to deliver; generation and production collapse into one step. (Omit model for the Nano Banana default; target defaults to a short-lived temporary asset if you'd rather not persist.)

The takeaway

The honest version: if all you need is the cheapest bucket, R2 wins on raw storage cost, and Supabase now bundles basic transforms and a CDN. Reach for a full media platform when the whole job matters (persist, transform, deliver, keep on-brand, organise) and you'd rather make one call than orchestrate five.

But the broader lesson outlives any product choice. In an agentic system, a generated file is an intermediate value, not a deliverable. The model is a component, not the finish line. Treat the path from raw output to production asset as a real pipeline (whether you build it from buckets, workers, transcoders and a metadata table, or hand it to something that does all five) and your agents stop storing links to nothing.

Cloudinary ❤️ developers
Ready to level up your media workflow? Start using Cloudinary for free and build better visual experiences today.
👉 Create your free account