BrainBrawl

• 

  Lobby page

• 

  Workflow of how our website works.

• 

  Battle Phase

• 

  Item Generator

• 

  Transition Page

• 

  Game Over Page

• 

  Victory Page

Inspiration

Our project was inspired by a shared common occurrence of us getting distracted by our phones and video games when we know we should study. The parts of the visuals were inspired by Slay the Spire and Souls-like video games.

What it does

It is a website that turns a student’s notes/lectures/exams into an interactive boss fight where the user has to answer a series of questions in order to defeat the enemy, who is given a personality based on the given documents.

How we built it

We built the frontend with Next.js and the backend with Flask. The AI pipeline uses Google Gemini to extract a knowledge graph from your uploaded PDF, generate themed bosses with their own personalities and dialogue, and produce questions dynamically based on the file uploaded. Everything would run in a Docker container.

Challenges we ran into

We faced a lot of issues with having the project run and behave the same across our computers. Communicating our ideas and avoiding confusion were something that we struggled with, as we didn’t create a detailed plan before diving into it. (We also leaked our API key more than once, which wasn’t great.)

Accomplishments that we're proud of

The frontend is where we dedicated the most passion and time, and we are incredibly proud of our visual aesthetic, raw retro animations, and audio design. As a team, we’re extremely proud of successfully bridging a complex AI backend with a highly interactive React state machine in such an intense time crunch.

What we learned

Prompt Engineering for Games: We learned how to manipulate Gemini not just for conversational AI, but as a live game engine. We designed strict JSON schemas so Gemini could reliably act as an "Adaptive Question Generator" and a "Game Judge" reacting in-character, without breaking the application logic.

Container Orchestration: We figured out how to bridge a modern Next.js frontend and a Python Flask backend, using Docker Compose to containerize everything so it easily builds and runs anywhere with a single command.

Managing Complex State: We leveled up our React skills by building a robust combat state machine. We learned how to safely handle asynchronous API calls (streaming questions), UI animations (boss attacks, damage numbers, HP bars), and real-time audio triggers without race conditions or hydration errors.

Extracting Knowledge Graphs: We learned how to parse unstructured data (messy PDF study notes) and use AI to extract hierarchical, structured "topics" and "concepts" to build our boss gauntlets dynamically.

What's next for BrainBrawl

• Adding progress tracking and weak-spot memory across multiple sessions.More boss abilities and mechanics.
• Implementing more boss abilities, attack mechanics, and a wider variety of unique equippable items.
• Adding more dynamic backgrounds, arenas, and environmental particle effects.
• Ensuring the overall user experience is as smooth and satisfying as a real commercial indie game.

Built With

• docker
• gemini
• next.js
• python
• render
• typescript
• vercel