A real-time, AI-judged competitive debate platform where users engage in structured 1v1 intellectual battles, scored by Google's Gemini AI across Logic, Facts, and Relevance — with Elo rankings, audience voting, and a community-driven topic ecosystem.
| Production URL | socratic-arena.vercel.app |
| Frontend Host | Vercel |
| Backend Host | Render |
| Database | Supabase (PostgreSQL) |
| Dashboard & Cognitive Profile | Live Debate Arena | Explore & Discovery Hub |
|---|---|---|
| Elo rating, radar chart, recent debates, social network | Real-time 1v1 with typewriter effect, turn timer, role badges | AI-categorized topics across 12 domains, trending arenas |
# 1. Clone
git clone https://github.com/Ayush-Kumar0207/The_Socratic_Arena.git
cd The_Socratic_Arena
# 2. Setup Backend
cd backend
npm install
cp .env.example .env # Fill in your keys (see Environment Variables below)
node server.js
# 3. Setup Frontend (new terminal)
cd frontend
npm install
npm run devOpen http://localhost:5173 — you're in the arena.
Socratic Arena can run high-accuracy speech-to-text without paid APIs by using the local faster-whisper service in stt_service/.
cd stt_service
.\start.ps1The frontend tries this order automatically:
- Local free STT at
http://127.0.0.1:5055 - Backend proxy at
/api/stt/transcribe - Browser
SpeechRecognitionfallback
This means users do not need Deepgram, Google STT, or OpenAI transcription credits. The only cost is the compute of whichever machine runs the open-source model.
- About The Project
- Features
- Tech Stack
- Architecture
- Project Structure
- Environment Variables
- Deployment
- Observability
- Roadmap
- Contributing
- License
- Author
The Socratic Arena transforms online discourse from chaotic arguments into structured, meaningful intellectual combat. Inspired by the Socratic method, every debate follows a deliberate format:
- Two players are assigned roles — Critic (challenges the thesis) and Defender (upholds it)
- A 5-minute timed round forces concise, high-quality arguments
- Gemini 2.5 Flash acts as an impartial AI Judge, scoring each debater on Logic, Facts, and Relevance
- The community votes during a 24-hour deliberation window, and an Elo rating system ranks debaters globally
Unlike social media flame wars, The Socratic Arena rewards thinking — not shouting.
- Real-time 1v1 debates via WebSocket with server-authoritative turn management.
- Dynamic Stance Mapping — Automatically parses debate topics (e.g., "Veg vs Non-Veg") to generate tailored, context-aware mission objectives for each role.
- Mission Briefing Ribbon — A glassmorphic, top-pinned UI component with
slideDownanimations that keeps your specific debate objective always in focus. - Critic vs. Defender roles — Internally mapped to dynamic stances to ensure database compatibility while providing clear, human-readable instructions.
- 5-minute countdown timer per debater with automatic match resolution.
- Typewriter message effect for a live, immersive feel.
- Private Arena codes — Invite a specific opponent with a shareable code (e.g.,
1AB6-X9K2).
- Direct Invitations — Send live P2P "Debate Challenges" to online users straight from their profile.
- Interactive Notification Bell — Accept or decline incoming challenges in real time.
- Auto-Lobby Routing — Seamlessly transports both players into a private arena upon challenge acceptance.
- Installable Desktop/Mobile App — Add to homescreen for a standalone, immersive experience.
- In-App 'Update Available' UI — Background service worker integration cleanly prompts for new updates via the Notification Bell.
- Offline Resilience — Employs custom toasts to gracefully warn users of lost network connections.
- Fully Responsive UI — The entire complex interface, from the Live Arena typewriter to radar charts, is intricately optimized for mobile dimensions.
- Touch Navigation — Streamlined bottom sheets and modal dialogs designed for touch interactions.
- Abandoned Match Handling — Live Arenas instantly detects and cleans up abandoned matches, ensuring precise stat tracking.
- Acoustic-Semantic Lock — High-fidelity audio analysis that distinguishes between dictation and commands with precise temporal and semantic gates.
- Affective Punctuation — Automatically appends
?,!, or...based on vocal energy peaks (RMS), interrogation patterns, and pauses (Delta-T). - Tone-Aware Visual Auras — Messages are rendered with vibrant, pulsing glows (Rose for Urgent, Indigo for Inquisitive) synced in real-time across all clients.
- Text-Voice Parity — A lightweight semantic scanner ensures that manually typed messages (e.g., "This is ridiculous!!!") receive the same visual "Aura" and metadata as voice messages.
- Hardware-Level Fidelity — Explicit
autoGainControlmanagement to preserve natural vocal intensity for emotion detection.
- Gemini 2.5 Flash evaluates every debate on three axes: Logic, Facts, and Relevance (1–10 scale).
- AI Topic Categorization — New topics are automatically classified into 12 domains using Gemini-powered domain analysis.
- AI Bouncer — Validates and deduplicates new topics using semantic similarity analysis.
- AI-powered semantic search — Find debates by conceptual meaning rather than just keyword matches.
- Elo rating system with dynamic K-factor (50 for new players, 30 standard, 15 for elite)
- 5 rank tiers: Novice → Thinker → Scholar → Philosopher → Oracle
- Performance bonus: +5 Elo for winning with 90%+ audience support
- Cognitive Profile radar chart tracking average Logic, Facts, and Relevance scores
- 24-hour deliberation window for audience voting after each debate
- Composite scoring: 70% AI Judge + 30% Audience Sentiment
- Live spectating — watch active debates in real time
- Follow debaters and see their live status on your Dashboard network widget
- Discovery Hub in My Arena — topics grouped across 12 AI-detected categories (Technology, Philosophy, Sports, etc.)
- Trending Arenas in Explore — sorted by popularity with personalized tiebreakers
- Broad Topics Library — 56 curated debate prompts spanning science, politics, ethics, and more
- Dynamic topic creation from search bar or Create Arena dialog with AI category correction
- Match Review page with detailed AI scores, radar comparison charts, and bar graphs
- Debate transcript replay with timed playback recreating the original pace
- Popular topics sidebar for discovery after reviewing a match
| Layer | Technology | Purpose |
|---|---|---|
| Frontend | React 19, Vite 7, TailwindCSS 4 | Component-driven SPA with HMR |
| UI Components | Lucide React, Recharts | Icons, radar/bar charts |
| Realtime | Socket.IO Client/Server | Bidirectional WebSocket communication |
| Backend | Node.js, Express 4 | REST API + Socket.IO server |
| AI Engine | Google Gemini 2.5 Flash | Debate evaluation, topic classification, semantic analysis |
| AI Framework | LangChain + Google GenAI | Structured AI chains, embeddings, semantic search |
| Database | Supabase (PostgreSQL) | Auth, profiles, matches, topics, votes, real-time subscriptions |
| Auth | Supabase Auth | OAuth / email authentication |
| Export Tools | html2canvas | UI snapshots and visual state capture |
| Routing | React Router DOM v7 | Client-side navigation with protected routes |
┌──────────────────────────────────────────────────────────────────┐
│ CLIENT (React SPA) │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────────────┐ │
│ │Dashboard │ │ Lobby │ │ Arena │ │ Explore / MyArena │ │
│ │(Profile) │ │(Match) │ │(Debate) │ │ (Discovery Hub) │ │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ └──────────┬───────────┘ │
│ │ │ │ │ │
│ └─────────────┴────────────┴───────────────────┘ │
│ │ Socket.IO │ Supabase Client │
└──────────────────────────┼────────────┼────────────────────────────┘
│ │
┌──────▼────────────▼──────┐
│ SERVER (Node.js) │
│ ┌────────────────────┐ │
│ │ Socket.IO Handlers │ │
│ │ • Matchmaking │ │
│ │ • Turn Management │ │
│ │ • Private Arenas │ │
│ │ • Topic Proposals │ │
│ └────────┬───────────┘ │
│ │ │
│ ┌────────▼───────────┐ │
│ │ Gemini AI Engine │ │
│ │ • Debate Scoring │ │
│ │ • Category Detect │ │
│ │ • Semantic Search │ │
│ │ • Topic Validation │ │
│ └────────┬───────────┘ │
│ │ │
│ ┌────────▼───────────┐ │
│ │ Elo Rating Engine │ │
│ │ • K-Factor Calc │ │
│ │ • Win Resolution │ │
│ │ • Performance Bonus│ │
│ └───────────────────┘ │
└──────────┬────────────────┘
│
┌──────────▼────────────────┐
│ SUPABASE (PostgreSQL) │
│ profiles │ matches │
│ topics │ votes │
│ topic_follows │ private_arenas │
└───────────────────────────┘
The_Socratic_Arena/
├── backend/
│ ├── server.js # Main entry — Express + Socket.IO + AI Engine (1700 LOC)
│ ├── auto_seed.js # Auto-seeds broad topics on startup
│ ├── package.json
│ ├── .env # Environment variables
│ ├── controllers/ # REST API controllers
│ ├── routes/
│ │ └── apiRoutes.js # HTTP API endpoints
│ ├── lib/
│ │ └── supabaseClient.js # Supabase admin client
│ ├── services/ # Business logic services
│ └── migrations/ # Database migration scripts
│
├── frontend/
│ └── src/
│ ├── App.jsx # Root — routing, auth, Create/Join Arena dialogs
│ ├── main.jsx # React DOM entry point
│ ├── components/
│ │ ├── Login.jsx # Auth page (Supabase OAuth)
│ │ ├── Dashboard.jsx # Player profile, Elo, radar chart, network
│ │ ├── Explore.jsx # Browse topics, live matches, leaderboard, search
│ │ ├── MyArena.jsx # Discovery Hub, trending debates, saved arenas
│ │ ├── Lobby.jsx # Matchmaking + private arena code system
│ │ ├── DebateArena.jsx # Live 1v1 debate with typewriter & turn timer
│ │ ├── MatchReview.jsx # Post-match analytics, voting, replay, charts
│ │ ├── TopicMatches.jsx # All matches for a specific topic
│ │ ├── Navbar.jsx # Navigation bar
│ │ ├── ProfileModal.jsx # User profile popup with follow system
│ │ └── FileUploader.jsx # File upload utility
│ ├── lib/
│ │ ├── supabaseClient.js # Supabase browser client
│ │ └── domainUtils.js # 12-domain topic classification + keyword engine
│ ├── hooks/ # Custom React hooks
│ └── services/ # API service layer
│
└── schema.sql # Database schema (5 tables + RPC function)
Create a .env file in the backend/ directory:
# Server
PORT=5000
# Supabase — Get from https://supabase.com/dashboard
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_KEY=your-service-role-key
# Google Gemini AI — Get from https://aistudio.google.com
GEMINI_API_KEY=your-gemini-api-key
# Feature Flags
ENABLE_ADVANCED_AI=true # Toggle AI evaluation (set false to reduce API costs)Create a .env or update the Supabase config in frontend/src/lib/supabaseClient.js with your project's public anon key and URL.
# Terminal 1: Backend
cd backend && npm install && node server.js
# ✅ Server running on http://localhost:5000
# Terminal 2: Frontend
cd frontend && npm install && npm run dev
# ✅ App running on http://localhost:5173- Push the repo to GitHub
- Import the project on Vercel
- Set the Root Directory to
frontend - Build Command:
npm run build - Output Directory:
dist - Add environment variables for Supabase (public anon key + URL)
- Deploy → live at
your-project.vercel.app
- Create a new Web Service on Render
- Set the Root Directory to
backend - Build Command:
npm install - Start Command:
node server.js - Add all environment variables from
.env(Supabase, Gemini, etc.) - Update the frontend's Socket.IO URL to point to your Render URL
- Create a new project on Supabase
- Run
schema.sqlin the Supabase SQL Editor to create tables - Enable Row Level Security as needed
- Copy your project URL and service key into
backend/.env
The backend exposes Prometheus metrics at GET /metrics and a health probe at GET /health. A local monitoring stack is included under observability/ with Prometheus, Grafana, and Alertmanager.
# Terminal 1: backend metrics source
cd backend
$env:ALERT_WEBHOOK_SECRET="local-alert-secret"
npm run dev
# Terminal 2: Prometheus + Grafana + Alertmanager
docker compose -f observability/docker-compose.yml up -d --pull neverOpen Grafana at http://localhost:3001 with admin / admin, then load the Socratic Arena Robustness Overview dashboard. For automatic Discord/Slack-style alerts, set ALERT_WEBHOOK_URL before starting Docker Compose; the independent alert relay still works if the backend crashes.
Full runbook: observability/README.md.
Robustness proof and screenshots: docs/robustness/README.md.
- Real-time 1v1 debate engine with server-authoritative turns
- AI Judge scoring (Logic, Facts, Relevance) via Gemini 2.5 Flash
- Elo ranking system with 5 rank tiers
- Private Arena codes for invite-only debates
- 24-hour audience deliberation and voting
- Discovery Hub with AI-powered topic categorization (12 domains)
- Semantic search via LangChain
- Match replay with timed playback
- Cognitive Profile radar charts
- Social network (follow users, see live status)
- Real-time P2P Challenge System with interactive notifications
- Progressive Web App (PWA) integration and offline support
- Fully responsive mobile-first UI optimization
- Abandoned Match UI cleanup and precise stat tracking
- AI Judge Lifeline — Summon the AI to fact-check mid-debate (Objection System)
- Pragmatic Affective Engine v2 — Tone detection, auto-punctuation, and visual auras
- Dynamic Stance Mapping — tailored objectives for comparitive topics
- AI Highlights — Automatically generate and extract key turning points from debates
- PDF & Text Export — Download professional-grade debate transcripts
- Tournament brackets with elimination rounds
- Team debates (2v2)
- Mobile-native app (React Native)
- Public API for third-party integrations
Contributions make the open-source community thrive. Any contribution is greatly appreciated.
- Fork the repository
- Create your feature branch (
git checkout -b feature/AmazingFeature) - Commit your changes (
git commit -m 'Add AmazingFeature') - Push to the branch (
git push origin feature/AmazingFeature) - Open a Pull Request
- Follow the existing code style and component patterns
- Add meaningful comments for complex logic
- Test Socket.IO events with multiple browser tabs
- Keep the backend server-authoritative — never trust the client
How does the AI Judge evaluate debates?
Gemini 2.5 Flash analyzes the full transcript and scores each debater on Logic (argument structure), Facts (accuracy of claims), and Relevance (staying on topic), each on a 1–10 scale. The composite winner is determined by 70% AI score + 30% audience vote.
How are the Critic and Defender roles assigned?
The platform uses Dynamic Stance Mapping. When a topic is searched or created (e.g., "AI vs. Humans"), the system automatically parses the prompt and generates tailored, context-aware mission objectives for each role (Stance A and Stance B). Roles are then assigned based on who joins first, or randomly in paired matches.
How does the Voice Affective Engine work?
The Socratic Arena uses a high-fidelity Acoustic-Semantic Lock. It distinguishes between dictation and commands, automatically appends punctuation based on vocal peaks (Interrogation patterns/RMS), and renders your messages with vibrant, pulsing Visual Auras (Indigo for Inquisitive, Rose for Urgent) synced in real-time across all clients.
What happens if someone disconnects mid-debate?
The system detects disconnection via Socket.IO, waits 30 seconds for reconnection, then automatically marks the match as "abandoned." The remaining player receives an Elo advantage, and the match transcript is preserved for review.
How does the Elo system work and what are the ranks?
We use a dynamic K-factor: K=50 for newcomers (< 10 matches), K=30 for established, and K=15 for elite (> 1800 Elo). As you climb, you progress through 5 tiers: Novice → Thinker → Scholar → Philosopher → Oracle. Oracle status is reserved for the absolute elite of intellectual combat.
What is the significance of the 24-hour deliberation period?
Every debate remains "In Deliberation" for 24 hours to allow the community to watch and vote. This ensures the 30% audience weight is statistically significant, countering any potential AI bias and rewarding debaters who resonate with human reason.
Can I create my own debate topics?
Yes! Use the search bar on the Explore page or the "Create Arena" button. New topics are validated by our AI Bouncer (to prevent duplicates/spam) and automatically categorized using Gemini-powered domain analysis before being published to the Discovery Hub.
Can I install The Socratic Arena as an app?
Yes! The platform is a fully compliant Progressive Web App (PWA). Simply click "Install" in your browser's address bar or add it to your home screen on mobile. You'll receive real-time update notifications and benefit from offline resilience.
Distributed under the MIT License. See LICENSE for more information.
Ayush Kumar — @Ayush-Kumar0207
Ravi Prashant — @cypher00grd
Ayush Kumar Full Stack & Core Development |
Ravi Prashant Full Stack & Core Development |
Built with passion for structured discourse and the belief that better debates make better thinkers.
If this project sharpened your thinking, consider giving it a ⭐
Every star fuels better debates.