DebateOS — AI + Reasoning + Critical Thinking

A full-stack web product where two AI agents argue opposite sides of any claim using real web evidence. A judge scores every argument. Fallacies are caught live. Users build a Critical Thinking Score over time.

---

What's built (52 files)

Backend

Module	What it does
agents/	Prosecutor, Defender, Judge, Fallacy Detector — all Gemini-powered
rag/	Tavily web search → ChromaDB vector store → citation in every argument
graph/	LangGraph debate loop, state schema
db/	Supabase client, full Postgres schema, all SQL functions
api/main.py	FastAPI — 15 endpoints including SSE stream, PDF upload, DOTD, scores
jobs/daily_debate.py	Cron job — fetches news, generates daily claim, saves to DB

Frontend (10 pages)

Route	Page
/	Landing page — live demo, Debate of the Day, pricing, modes
/debate	Debate arena — full live debate with SSE streaming
/human-vs-ai	Human vs AI — you argue, Gemini responds, judge scores
/trending	Most debated claims this week
/leaderboard	Fallacy leaderboard
/scores	Critical thinking score rankings
/profile	Your score, tier, streak, skill breakdown
/history	Your past debates
/debate/:id	Public share page
/auth/callback	OAuth redirect

---

Setup

Get API keys (all free tier available)

• GEMINI_API_KEY → aistudio.google.com
• TAVILY_API_KEY → tavily.com (1000 searches/month free)
• SUPABASE_URL + keys → supabase.com → project → Settings → API
• GNEWS_API_KEY → gnews.io (100 requests/day free) — optional, fallback claims used if missing

Backend

cd backend
python -m venv venv
source venv/bin/activate   # Windows: venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env       # fill in your keys
python run.py              # → http://localhost:8000

Database

Paste backend/db/schema.sql into Supabase SQL Editor → Run. Enable Google OAuth: Supabase → Authentication → Providers → Google.

Frontend

cd frontend
npm install
cp .env.example .env       # fill in VITE_SUPABASE_URL + VITE_SUPABASE_ANON_KEY
npm run dev                # → http://localhost:5173

Debate of the Day cron job

Run daily at 6 AM. On Railway: add cron job python -m jobs.daily_debate with schedule 0 6 * * *. Locally: python -m jobs.daily_debate

---

Deploy

Backend → Railway: push to GitHub → connect Railway → set root to backend/ → add env vars. Dockerfile auto-detected.

Frontend → Vercel: cd frontend && vercel --prod. Set 3 env vars in Vercel dashboard: VITE_SUPABASE_URL, VITE_SUPABASE_ANON_KEY, VITE_API_URL (your Railway URL).

---

Revenue model

• Free: 3 debates/day
• Pro $9/mo: unlimited + Human vs AI + history + PDF debates
• Teams $49/mo: 5 seats + teacher dashboard + shared workspace
• Enterprise $499/mo: API access + white-label + SSO