BrainDrop

Work in progress · my first full-stack project. Some rough edges remain (see Known issues below) but the core flow works end-to-end.

A small full-stack logic puzzle app — riddles, AI-judged free-text answers, AI-hosted yes/no questioning, chess-style ELO rating, hint system, EN/HU localization, three theme palettes (Paper / Sage / Mist) × light/dark.

Stack

Backend: Python 3.11+ · FastAPI · SQLite (WAL mode) · JWT + bcrypt auth
Frontend: React 18 · Vite · vanilla CSS
AI: Gemini + Groq dual-provider with automatic failover

Features

Auth (JWT, bcrypt) + guest mode AI judges free-text answers Yes/no AI questioning system ELO rating + hint/penalty system EN/HU support + themes

How this was built

This project was built using AI coding agents (Claude Code + Codex) with me directing the architecture, design iteration, and testing.

I scoped the requirements, made design and tech decisions, found bugs through real usage, and iterated on the AI prompts and product logic. The agents wrote the bulk of the implementation code under my direction.

This is my first serious full-stack project. I'm using it to learn the moving parts of a modern web app: FastAPI routing, JWT auth, SQLite schema design with WAL mode, React state management, LLM prompt engineering, and provider-agnostic API design.

Known issues

• After a page refresh mid-puzzle, the player loses the in-progress puzzle and is sent back to the landing screen. The backend already deducts the abandonment penalty correctly; resuming the puzzle on reload is not yet wired up on the frontend.
• Gemini's free-tier rate limit (50 req/day) is easy to hit during dev — the Groq fallback handles this transparently.
• Hint translations are pre-defined for the 15 puzzles, but AI-generated hints don't yet re-translate when the language is switched mid-puzzle.
• The 15 puzzles are classic well-known problems. Curating original puzzles is a future task.
• Review mode can still show Megoldva · +0 ELO; solved puzzles should always award at least +1 ELO.
• Free AI model quality is still under evaluation. Some providers may accept weak answers too easily or misclassify yes/no questions.
• The ask system still needs tuning: invalid/rude detection must work in both EN and HU without blocking legitimate puzzle questions.
• Rude ask styling is incomplete: kind: "rude" should render in the warning color instead of relying on response text.

Structure

• backend/app/main.py wires the API app, CORS, database init, and routers
• backend/app/routers contains the HTTP endpoints (auth, puzzles, leaderboard)
• backend/app/services contains app logic such as ELO and AI helpers
• backend/app/schemas contains Pydantic request validation models
• backend/app/db/database.py owns SQLite persistence and puzzle seed data
• frontend/src contains the React app (braindrop-*.jsx, braindrop.css)

Run Locally

Backend (port 8001 — the frontend hardcodes this in braindrop-core.jsx):

cd backend
python -m uvicorn main:app --reload --host 127.0.0.1 --port 8001

Frontend:

cd frontend
npm install
npm run dev

Open http://127.0.0.1:5500.

Environment

Create backend/.env and set your local API keys there. Use backend/.env.example as the template.

API keys:

• Gemini: https://aistudio.google.com/app/api-keys
• Groq: https://console.groq.com/keys

Generate JWT_SECRET with:

python -c "import secrets; print(secrets.token_urlsafe(64))"