Submitted to the USAII Hackathon 2026 · React + FastAPI + Supabase + OpenRouter
Demo
What It Does
The core loop: Sign up with a magic link → quick onboarding captures your goals, strengths, weaknesses, interests, and learning style → AI matches you to a compatible Village → inside your Village you get a real-time discussion feed, an AI Village Elder that drops prompts, AI study challenges, a Topic Explorer for breaking down confusing subjects, and AI-generated collaborative learning paths for the group.
Study Hub:Beyond villages, there's a full personal study suite — a Socratic-method Study Buddy that never gives direct answers, an Essay Coach that critiques without ghostwriting, a multi-week Study Planner that works backward from your deadline, and College Prep tools (essay workshop + college fit advisor).
Courses: Teachers can create courses with lesson completion tracking, verified badges, and AI-generated study tips per course.
Architecture
Villages — Three-Tier Architecture
═══════════════════════════════════
Users → https://villages-eight.vercel.app
│
┌───────┴───────┐
│ Frontend │ ← React 18 + Vite + Tailwind CSS
│ (Vercel) │ Auth gate, routing, realtime
└───────┬───────┘
│ /api/* → villages-api.vercel.app
┌───────┴───────┐
│ Backend │ ← FastAPI on @vercel/python
│ (Vercel) │ REST endpoints for users,
│ │ villages, posts, AI, courses
└───────┬───────┘
│ service_role_key
┌───────┴───────┐
│ Supabase │ ← PostgreSQL + Auth + Realtime
│ (free tier) │ Tables: profiles, villages,
│ │ posts, comments, challenges
└───────────────┘
AI: OpenRouter free-tier (:free models, $0 cost)
Deploy: Vercel (frontend + backend serverless)Everything runs on free tiers — Supabase free, Vercel Hobby, OpenRouter :free models. Zero monthly cost.Backend Sneak Peek
Live API: Checking...
backend/app/services/ai_service.py
async def generate_village_match_reasoning(
user_goals: list[str],
user_strengths: list[str],
user_weaknesses: list[str],
academic_level: str,
interests: list[str] = None,
learning_style: str = "visual",
available_villages: list[dict] = None,
) -> dict:
"""Match a user to the best-fit village using AI reasoning."""
village_summaries = "\n".join(
f"- ID: {v['id']} | Name: {v['name']} | "
f"Focus: {v['focus_area']} | Members: "
f"{v['member_count']}/{v['max_members']}"
for v in available_villages
if v["member_count"] < v["max_members"]
)
system = (
"You are an AI matching system for Villages. "
"Analyse the user's profile against available villages "
"and return a JSON with village_id and reasoning."
)
return await call_llm(messages, system=system)Key Features
AI Village Matching
LLM analyses goals, strengths, weaknesses, interests, and learning style — then places you in the most compatible Village with available slots.
Real-Time Discussion
Supabase Realtime powers live feeds. Posts and comments appear instantly. Global forum for cross-village conversation.
AI Village Elder
Generates warm, academically-focused discussion prompts. Posts appear as the “Village Elder” in the feed with a bot icon.
AI Study Challenges
Type any subject + difficulty → get a collaborative challenge with title, description, and step-by-step instructions.
Topic Explorer
Paste any confusing topic → AI breaks it into plain language, a checklist, and next steps. Responsible AI guardrails check every output for safety and accuracy.
AI Learning Paths
Group-level curriculum designer: generates a structured multi-step plan tailored to the Village's focus area, resources, and shared interests.
Study Hub
Socratic Study Buddy, Essay Coach, multi-week Study Planner, and College Prep (essay workshop + college fit advisor). Access-gated by academic level.
Content Moderation
Every post, comment, and AI explanation passes through a moderation guardrail for safety, accuracy, and inclusivity before reaching users.
Dev Notes
Tech Stack
React 18 + Vite + Tailwind CSS (frontend), FastAPI + Uvicorn (backend), Supabase (PostgreSQL, auth, realtime), OpenRouter free-tier LLMs. Vercel for both frontend and backend serverless.
Hardest Part
Supabase magic link SITE_URL bug — stuck at localhost in production. Fixed by building a backend proxy that follows the 303 redirect, extracts session tokens from the hash fragment, and reconstructs the callback URL for the real domain. Took days.
What I Learned
Supabase Realtime is genuinely impressive after you work around its quirks. Prompt engineering for group-level AI features (learning paths for 6 people with different interests) is harder than individual AI. Scope management is everything.
Cost
Zero. Supabase free tier (500MB DB, 50k users), Vercel Hobby (100GB bandwidth), OpenRouter :free models (28+ models, 50 req/day). No API credits or subscriptions.