knighshi try here!
Knightshi is a UCF-themed binary prediction-market simulation built with virtual credits for the BloomKnights competition. Users buy YES/NO shares in demo markets, prices move through a constant-product market maker (CPMM), and belief-driven bots simulate a crowd so judges can watch prices converge toward a hidden probability in real time.
This is a simulation only. It uses virtual credits and is not gambling.
| Market | Resolves via | Demo state |
|---|---|---|
| UCF football historical replay | ESPN box score | Resolvable |
| COP3502 Exam 1 mean >= 80 | Canvas instructor post | Resolvable |
| UCF Fall 2026 enrollment > 75,000 | Official enrollment figure | Left open/unresolved |
| UCF covers the spread vs USF | Box score + published line | Proof of concept |
| UCF Hackathon 2026 draws 400+ hackers | Organizer headcount | Proof of concept |
| Meal-plan base price flat Fall 2026 | Housing published rates | Proof of concept |
- Frontend: React 18, TypeScript, Vite, Tailwind CSS, Framer Motion, Recharts, Supabase Realtime.
- Backend: FastAPI, SQLAlchemy, Alembic, Supabase Postgres, JWT auth.
- AI: Gemini through
google-genaifor one insight feature. - Auth: Google OAuth or demo email login with an app JWT.
graph TB
subgraph Client["Frontend - React + Vite + Tailwind"]
UI["Market UI + Recharts chart"]
TP["Trade panel"]
RTHook["Realtime trade hook + polling fallback"]
end
subgraph Backend["FastAPI Backend"]
AUTH["Google OAuth -> app JWT"]
ROUTES["Markets, trades, positions, admin"]
AMM["CPMM service"]
BOTS["Belief-driven bots"]
AI["Gemini insight engine"]
end
subgraph Data["Supabase"]
PG[("Postgres")]
RT["Realtime postgres_changes"]
end
subgraph External["External APIs"]
GEM["Google Gemini API"]
end
UI --> ROUTES
TP --> ROUTES
RTHook -. subscribe .-> RT
ROUTES --> AUTH
ROUTES --> AMM
ROUTES --> AI
AMM --> PG
BOTS --> ROUTES
AI --> GEM
PG --> RT
RT -. push .-> RTHook
Each market has YES and NO liquidity pools. The market maker preserves x * y = k, where x is the YES pool and y is the NO pool. A YES price is read approximately as y / (x + y).
Trades update the pools, user positions, and trade history. Supabase Realtime pushes new trades to connected clients, with a 3-second polling fallback for demo safety.
Admin-triggered bots trade from private beliefs sampled around a hardcoded p_true, creating the live convergence that makes the demo readable without needing a large audience.
Knightshi/
├── README.md
├── LICENSE.md
├── AGENTS.md
├── CLAUDE.md
├── DESIGN.md
├── MOTION.md
├── .env.example
├── docs/
│ └── RAILWAY.md
├── backend/
│ ├── main.py
│ ├── auth/
│ ├── models/
│ ├── routes/
│ ├── services/
│ ├── bots/
│ ├── ai/
│ ├── realtime/
│ └── migrations/
└── frontend/
├── vite.config.ts
├── public/
└── src/
├── components/
├── hooks/
├── lib/
├── motion/
└── pages/
Prerequisites:
- Node.js 20+.
- Python 3.11+.
- A Supabase project with Postgres.
- Google OAuth credentials (optional for local demo — email login works).
- A Gemini API key from Google AI Studio (optional; insight degrades safely when unset).
Create your local environment file:
cp .env.example .envFill in the blank values in .env. Never commit real secrets.
Backend:
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
alembic -c alembic.ini upgrade head
python -m backend.seedFrontend:
cd frontend && npm installKeep dependencies in .venv and frontend/node_modules — do not commit them. Run the API with uvicorn; it exposes /health. The frontend points to it through VITE_API_BASE_URL. Gemini insight degrades to a calm fallback whenever GEMINI_API_KEY is unset, so the trading core never depends on the AI being up.
Production uses two Railway services (API + frontend SPA). See docs/RAILWAY.md for root directories, env vars, and the VITE_API_BASE_URL deploy order.
Start both services (two terminals, from repo root):
source .venv/bin/activate && uvicorn backend.main:app --reload --port 8000
cd frontend && npm install && npm run dev # http://localhost:5173Optional clean slate — resets demo markets to 0.50, wipes their trades/positions, and restores wallets to the initial grant (dev DB only):
python -m backend.seed --reset-demoDemo path:
- Browse the landing page at
http://localhost:5173/— animated hero, market preview, and campus demo sections. - Sign in at
/loginwith an email listed inADMIN_EMAILS(Google or demo email login). - Open the UCF football market — probability bar and price chart on screen.
- From Admin, start Simulate — bot trades land every 1–3 s and the price converges toward the hidden
p_truelive. - On the market page, click Get insight — Gemini explains the price action in plain English.
- Visit AI Brief (
/features) — one Gemini read per market, auto-loaded. - Stop the simulation, then Resolve the market from Admin to show payouts and portfolio P/L.
Note
If Google sign-in complains about origins, use demo email login the whole path works without Google, Supabase, or Gemini being reachable.
source .venv/bin/activate && pytest backend/tests
cd frontend && npm testFor AI-assisted development, start new coding sessions by reading:
AGENTS.mdfor build order, locked decisions, and guardrails..cursor/rules/*.mdcfor Cursor-scoped coding rules.CLAUDE.mdfor Claude Code session bootstrap.DESIGN.mdfor UI tokens and frontend design guidance.MOTION.mdfor Framer Motion choreography on the landing route.
MIT — see LICENSE.md.
Knightshi is a prediction-market simulation for demonstration and education. It uses virtual credits only.
