How DESAFIA Quiz Works

DESAFIA Quiz is an autonomous AI agent that helps indie hackers learn across 8 domains — vibecoding, strategy, product, marketing, finance, automation, agents, and blockchain — through a daily Duolingo-style quiz with a spinning category roulette.

Every morning the agent scrapes ~130 articles from RSS feeds, Reddit, and Hacker News, ranks the most actionable ones, and generates ≥3 questions per category (filling gaps with evergreen tips when needed).

The entire pipeline runs as a durable Vercel Workflow that survives crashes, retries failed steps, and triggers daily via Vercel Cron. Questions teach a pattern, command, prompt, or best practice you can apply to your project today.

This project is a textbook fit for Track 1 (WDK) because the core value is a long-running, multi-step async pipeline that needs durability guarantees:

• Multi-step pipeline — scrape RSS + Reddit + HN, rank, generate per-article questions, fill category gaps with evergreen, persist to Supabase. Each step is wrapped with "use step" for automatic retry and persistence.
• Crash recovery — if AI generation fails on article #5 of 8, WDK resumes from where it left off. No re-scraping, no duplicate articles, no wasted LLM calls.
• Scheduled execution — triggered daily at 6 AM UTC via Vercel Cron. WDK handles the lifecycle: queue, execute, retry, complete.
• Not a chatbot — this isn't a conversational UI (Track 3) or a rapid prototype (Track 2). It's a background agent that does real work autonomously.

Each category has its own emoji, color, EN/ES name, tagline, and AI topic hints. Every question generated is tagged with exactly one of these.

The workflow file at app/workflows/daily-news/workflow.ts starts with the "use workflow" directive. This tells the WDK compiler to transform the function into a durable workflow that Vercel can orchestrate.

Each step function uses "use step" which means:

• Automatic retry — if a step fails (network error, API timeout), WDK retries it up to 3 times automatically.
• Result caching — once a step succeeds, its result is persisted. If the workflow crashes later, completed steps are not re-executed.
• Full Node.js access — steps can make HTTP requests, call databases, run AI models.
• Observability — every step execution is visible in the Vercel dashboard under Workflow runs.

When deployed, Vercel automatically provisions the .well-known/workflow/v1/ endpoints for queue management, step execution, and webhook handling.

The quiz generator uses generateObject() from the Vercel AI SDK with a strict Zod schema. This guarantees the LLM output is always valid, typed, and ready to insert:

// Zod schema enforces structure
const questionSchema = z.object({
  type: z.enum(["multiple_choice", "fill_blank",
                 "true_false", "drag_drop"]),
  question: z.string(),
  options: z.array(z.string()).optional(),
  correctAnswer: z.string(),
  explanation: z.string(),
  actionTip: z.string(),
  difficulty: z.enum(["easy", "medium", "hard"]),
  category: CategoryEnum, // 1 of 8 indie-hacker domains
});

// AI SDK generates typed objects, not raw text
const { object } = await generateObject({
  model: gateway("google/gemini-2.5-flash-lite"),
  schema: quizGenerationSchema,
  prompt: `Generate 2 educational questions...`,
});

This is critical for reliability: no JSON parsing, no regex extraction, no hope-it-works. The AI SDK validates the output against the schema and retries if the LLM produces malformed data.

All sources are 100% free and curated to cover all 8 indie-hacker categories. No paid Twitter API, no scrapers that break:

All scrapers run in parallel (~130 articles/day). After deduplication and AI ranking, articles drive question generation. Categories with <3 questions are filled with evergreen tips so every category is always playable.

All data is stored in Supabase (Postgres) with Row Level Security enabled on every table:

articles            ─ Scraped news + bullet_points (jsonb)
daily_quizzes       ─ One per day (date unique) + theme
questions           ─ ~24-30/day, 3+ per category
                     fields: type, question, options,
                     correct_answer, explanation,
                     action_tip, difficulty, category
quiz_translations   ─ Cached on-demand AI translations
user_progress       ─ Per-visitor quiz results by date
user_stats          ─ streaks (current + max), total quizzes
saved_tips          ─ User-saved tips (per visitor)

API routes use the service_role key for writes (server-side only, never exposed to the client). Read policies are public since quiz content is not sensitive. Articles, questions, and translations are public; user_progress and user_stats are anonymous (visitor_id from localStorage).

The quiz UI is inspired by Duolingo with four question types and a focused progression model.

The whole platform runs on free tiers + a tiny AI bill. Here's the daily breakdown:

Why it stays cheap at any scale

All expensive AI calls run once per day in the workflow and the result is cached in the database. Whether you have 1 user or 10K users, the AI cost stays the same. Per-user actions (validate, submit, fetch quiz) hit Supabase directly with no AI involved.

# Daily AI cost breakdown
Ranker (1 call):           ~3,050 tokens   →  ~$0.0003
Article generation (×8):   ~16,800 tokens  →  ~$0.0034
Evergreen fill (≤8):       ~9,000 tokens   →  ~$0.0034
                           ─────────────
Total per day:             ~28,850 tokens  →  ~$0.007
Monthly (30 days):                        ~  $0.21

• RLS on all tables — Row Level Security enabled on every Supabase table. Public read policies for content, writes only via server-side API routes.
• No leaked answers — The /api/quiz/today endpoint strips correct_answer and explanation. Answers are only revealed after submission via /api/quiz/validate.
• Service role key server-only — The Supabase service_role key has no NEXT_PUBLIC_ prefix and is never sent to the browser.
• Cron auth — The /api/cron/daily-scraper endpoint verifies the CRON_SECRET bearer token in production.

This entire project was built in a single session with Claude Code (Anthropic's coding agent). Here's exactly how to replicate this workflow.

1Install Skills & MCPs

Skills give Claude domain knowledge. MCPs give it access to external services. Install them before you start prompting:

# Supabase skills (DB best practices + Supabase API)
npx skills add supabase/agent-skills

# Vercel skills (deployment + WDK + AI SDK)
npx skills add vercel

# UI/UX skill (50+ styles, 161 color palettes)
npx skills add nextlevelbuilder/ui-ux-pro-max-skill

# Configure Supabase MCP for direct DB access
# Create .mcp.json in project root:
{
  "mcpServers": {
    "supabase": {
      "url": "https://mcp.supabase.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_SUPABASE_ACCESS_TOKEN"
      }
    }
  }
}

2The Prompt That Built This App

Copy this prompt into Claude Code. It contains everything Claude needs to build the agent from zero:

I want to build an indie-hacker learning quiz platform for the Vercel hackathon (Track 1: Workflow SDK).

Product: a daily Duolingo-style quiz where the user spins a wheel to pick today's category from 8 indie-hacker domains: vibecoding, strategy, product, marketing, finance, automation, agents, blockchain.

The agent should:
1. Scrape relevant content from free sources every morning:
   - RSS: Anthropic blog, Vercel blog + changelog, GitHub releases (claude-code, vercel/ai), Indie Hackers, Latent Space, Lenny's Newsletter, Celo blog
   - Reddit RSS: r/ClaudeAI, r/ChatGPTCoding, r/cursor, r/indiehackers, r/SaaS, r/SideProject, r/n8n, r/celo, etc. (top of day)
   - Hacker News Algolia API: claude, v0, cursor, indie hackers, n8n, x402, stablecoin, celo (24h, points>20)
2. Use AI (Vercel AI Gateway with google/gemini-2.5-flash-lite) to:
   - Filter and rank top 8 most educational articles for indie hackers (reject generic news, drama)
   - Generate 2 LESSON-style questions per article (no trivia) tagged with one of the 8 categories
   - Fill gaps: for each category with <3 questions, generate 'evergreen' questions from category topic hints (no article needed)
3. Persist everything in Supabase (articles + bullet_points, daily_quizzes + theme, questions + category, user_progress, user_stats) with RLS enabled
4. Serve a Duolingo-style interactive web app with a spinning category roulette

Required stack:
- Next.js 15 (App Router)
- Vercel WDK ("use workflow" + "use step") for the durable pipeline
- Vercel AI SDK + AI Gateway (model: google/gemini-2.5-flash-lite)
- Supabase (Postgres + RLS on every table)
- Tailwind CSS + Framer Motion + Space Grotesk
- Vercel Cron daily at 6 AM UTC

Question types (4):
- Multiple choice (4 short options)
- Fill in the blank (with options)
- True/false
- Drag & drop (ordering)

Gamification:
- Day streaks + accuracy %
- In-quiz combo system (3 / 5 / 7 chains: Streak / On Fire / Master Streak)
- 60s per question with story-style timer (teal -> orange -> red)
- Pro Tip Reveal card after each answer with action tip
- Daily Cheat Sheet at the end (copyable)
- Share streak on X tagged @v0 @claudeai @desafiatech

Pages:
- / (landing with stats + 8-category preview + CTA)
- /quiz/[date] (roulette gating -> filtered quiz)
- /history (streak + accuracy stats)
- /docs (full bilingual documentation)

API routes:
- GET /api/quiz/today?locale= (today's quiz, no leaked answers)
- POST /api/quiz/validate (per-question validation)
- POST /api/quiz/submit (full submit + cheat sheet)
- GET /api/stats (streak + accuracy)
- POST /api/generate (manual trigger)
- GET /api/cron/daily-scraper (Vercel Cron)

Anonymous users via localStorage visitorId. Bilingual EN/ES with on-demand AI translation cached per-quiz.

Build the project, configure Supabase (create project + tables + RLS), set Vercel env vars, and deploy.

3What Claude Does From There

With that prompt + the skills installed, Claude will autonomously:

4Keys You'll Need

Pro Tips

• Let Claude plan first — When it enters Plan Mode, answer its questions about distribution, sources, and gamification. This saves massive rework later.
• Give it your API keys when it asks — Claude will configure Supabase, Vercel, and AI Gateway directly. It creates the DB, sets env vars, and deploys.
• Use the debug endpoint — Always add a GET route that prints config (key prefix, model, base URL) so you can diagnose issues in production without guessing.
• Pick one model and stick with it — Don't bounce between providers. We use google/gemini-2.5-flash-lite — fast, cheap, good enough for quiz generation.
• Deploy early — Push to Vercel after the first working feature. Every commit creates a preview. Fix issues in production, not localhost.