HackMaze

HackMaze is a competitive, maze-driven technical assessment platform originally built and deployed for at .

Designed for hackathons, college techfests, coding contests, recruitment-style elimination rounds, and internal technical events, HackMaze transforms traditional technical assessments into an interactive strategy-based challenge.

Participants progress through interconnected rooms by solving technical questions, unlocking doors, and strategically navigating through the maze before time runs out. Multiple branching paths, varying difficulty levels, and route optimization add both competitive pressure and decision-making depth to the experience.

The platform was successfully used during Horizon hackathon events and is now fully open-sourced so that colleges, coding clubs, communities, and event organizers can freely reuse, customize, and deploy it for their own competitions.

---

🚀 Features

🎮 Participant Experience

• Seamless participant login system
• Interactive maze-based gameplay
• Live topology map generated dynamically
• Multiple branching routes and varying difficulty paths
• Competitive time-based progression

🛡 Anti-Cheat & Tracking

• Focus-breach detection (tab switching / window exit tracking)
• Timestamped progression logging
• Participant activity monitoring
• Attempt and movement tracking

📊 Live Admin Dashboard

• Real-time leaderboard

• Participant status monitoring:

  • Active
  • Waiting
  • Completed
  • Quitted
  • TimeUp

• Room-wise participant distribution heatmap

• Live synchronization with the database

• Event-wide monitoring tools for organizers

---

🛠 Tech Stack

Backend

• Python
• Flask
• Waitress (Production WSGI Server)

Database

• SQLite
• SQLAlchemy ORM

Frontend

• HTML5
• Vanilla CSS
• Vanilla JavaScript
• Alpine.js

Visualization

• Viz.js
• Graphviz topology rendering

Package Management

• uv package manager

---

📂 Project Structure

.
├── app.py              # Core Flask application and routing
├── config.py           # Environment and app configuration
├── models.py           # SQLAlchemy database schemas
├── utils.py            # Maze parsing and distance algorithms
├── maze.json           # Maze topology and question bank
├── seed.py             # Bulk participant registration via CSV
├── serve.py            # Waitress production server entry point
├── templates/          # Jinja2 templates
└── static/             # Assets, stylesheets, and frontend scripts

---

⚙️ Setup Instructions

1. Clone the Repository

git clone https://github.com/LakhindarPal/HackMaze.git
cd HackMaze

---

2. Install Dependencies

HackMaze uses uv for fast and reliable dependency management.

uv sync

---

3. Configure Environment Variables

Copy the example environment file:

cp .env.example .env

Update the following values before deployment:

SECRET_KEY=your-secret-key
ADMIN_PASSWORD=your-admin-password

Always use strong production credentials for public deployments.

---

4. Seed Participants

Create a participants.csv file using the following format:

RollNumber,FullName,Department
2026001,John Doe,CSE
2026002,Jane Smith,ECE

Run the seeding script:

uv run seed.py

---

5. Start the Server

Launch the production-ready Waitress server:

uv run serve.py

---

🌐 Access URLs

Participant Portal

http://<host>:8080/

Admin Login

http://<host>:8080/admin

Admin Dashboard

http://<host>:8080/dashboard

---

🎨 Customization

Maze & Question Pool

Edit maze.json to:

• Change maze topology
• Add or remove rooms
• Modify branching paths
• Update question sets
• Tune difficulty levels

UI & Branding

Modify frontend styling from:

static/style.css

You can easily customize:

• Colors
• Typography
• Layout
• Branding
• Theme
• Animations

---

🧠 Possible Use Cases

HackMaze can be adapted for:

• College techfests
• Hackathons
• Coding competitions
• Technical treasure hunts
• Campus recruitment rounds
• Club events
• Internal assessments
• Workshop engagement activities

---

🔓 Open Source

HackMaze is now open-source and free to use for:

• Educational institutions
• Technical clubs
• Student communities
• Hackathon organizers
• Community-driven events

You are encouraged to customize, extend, and build upon the platform for your own competitions and events.

---

🙌 Acknowledgements

Originally built for organized by .

• Horizon Website: Horizon Techfest
• College Website: Dr. B. C. Roy Engineering College

---

📜 License

This project is open-source and intended for educational, competitive, and community event usage.