AI Arena is a competitive, multi-round, elimination-style web game where teams of players race to solve logic puzzles presented by a sentient Mars colony AI. This project demonstrates a full-stack application built with a Python/FastAPI backend, a React frontend, and a cloud-hosted MongoDB database, featuring real-time state management and dynamic content generation via the Groq LLM API.
- Real-time Multiplayer Lobby: Players can join a lobby and see other connected players in real-time.
- Team-Based Gameplay: An admin can dynamically create teams from the lobby to start the game.
- Dynamic Round System: A multi-round, elimination-style game where the lowest-scoring team is removed after each round.
- Live Game Dashboard: A main screen for players and admins to view a live leaderboard and a round countdown timer.
- AI-Powered Hints: Players can request hints for challenging subtasks, which are dynamically generated by the Groq LLM.
- AI-Generated Reports: At the end of the game, players receive a personalized "After-Action Report" narrated by the LLM, summarizing their performance.
- Full Admin Control Panel: A dedicated admin view to manage the entire game flow: resetting the game, creating teams, and starting rounds.
- Role-Based Access: A clear distinction between Player and Admin roles, with protected routes and conditional UI elements.
https://youtu.be/UeJvo70lnJw?feature=shared
- Framework: FastAPI
- Server: Uvicorn with Gunicorn for production
- Database: MongoDB (hosted on MongoDB Atlas)
- AI / LLM: Groq API (Llama 3)
- Libraries: Pydantic, PyMongo, python-dotenv
- Framework: React.js
- Styling: Tailwind CSS
- State Management: React Context API for global player state
- Routing: React Router
- Animations: Framer Motion
- Frontend: Vercel
- Backend: Render
- Database: MongoDB Atlas
Follow these instructions to get a copy of the project up and running on your local machine for development and testing purposes.
- Node.js and npm/yarn
- Python 3.10+ and pip
- MongoDB installed locally or a free MongoDB Atlas account
- A Groq API Key
# Navigate to the backend directory
cd backend
# Create and activate a virtual environment
python -m venv venv
# On Windows:
venv\Scripts\activate
# On macOS/Linux:
source venv/bin/activate
# Install the required packages
pip install -r requirements.txt
# Create a .env file and add your credentials
# (rename .env.example to .env and fill it out)backend/.env file:
MONGO_URI="your_mongodb_connection_string"
GROQ_API_KEY="your_groq_api_key"
# Run the backend server
uvicorn main:app --reloadThe backend will be running at http://127.0.0.1:8000.
# Navigate to the frontend directory
cd frontend-2.0
# Install dependencies
npm install
# Create a .env file for the frontendfrontend-2.0/.env file:
REACT_APP_API_URL="http://127.0.0.1:8000"
# Run the frontend development server
npm startThe frontend will be running at http://localhost:3000.
This application is configured for a seamless deployment process:
- Database: A free cluster is created on MongoDB Atlas.
- Backend: The
backendfolder is deployed as a Web Service on Render. TheMONGO_URIandGROQ_API_KEYare set as environment variables. - Frontend: The
frontend-2.0folder is deployed on Vercel. TheREACT_APP_API_URLenvironment variable is set to the live URL of the Render backend. - CORS: The live Vercel URL is added to the
originslist in the FastAPI backend to allow communication.
- WebSocket Integration: Replace HTTP polling with WebSockets for instant, real-time updates.
- Persistent Player Profiles: Allow users to create accounts and track their game history and stats.
- Expanded Content: Add more scenarios and more complex, varied subtask types.
- Time-Based Scoring: Introduce bonuses for finishing rounds quickly.