🧩 Puzzle Solver — AI-Powered 8-Puzzle Game

A full-stack AI puzzle game where users can play the classic 8-puzzle and get hints powered by search algorithms (BFS, Best-First Search, A*). Built with Next.js (frontend) and Python FastAPI (backend).

🚀 Live Demo

Service	URL
Frontend	puzzle-solver-uits-5b.vercel.app
Backend API	puzzle-solver-rjyx.onrender.com

✨ Features

• 🎮 Interactive 8‑puzzle board — click tiles to move them
• 🤖 AI hint system — tells you how many moves to solve
• 🔍 Multiple algorithms — BFS, Best‑First Search, A*
• 📱 QR code sharing — share any puzzle with a friend by scanning
• ✅ Solvability checker — only generates solvable puzzles
• 🎉 Win detection — congratulates you when solved manually

🎮 How to Play

Click the "How to play" button in the header to see a beautiful modal with full instructions. Here's a preview:

Quick rules:

• Move tiles adjacent to the empty space (click them).
• Arrange numbers from 1 to 8, with the empty tile at bottom-right.
• Press "Hint?" to get AI‑suggested minimum moves.
• Share any puzzle via the QR code on the right.

🧠 Algorithms Used

Algorithm	Type	Description
BFS	Uninformed	Explores all nodes level by level. Guarantees shortest path.
Best‑First Search	Informed	Greedy — always picks the node closest to goal using Manhattan distance.
A*	Informed	Optimal — combines path cost and heuristic for best performance.

🛠️ Tech Stack

Frontend

• Next.js 15 — React framework
• Tailwind CSS — styling
• React Icons — icons
• React Toastify — notifications
• Farmer Motion — animation

Backend

• FastAPI — Python API framework
• Uvicorn — ASGI server
• qrcode — QR code generation
• Pillow — image processing

⚙️ Local Setup

Prerequisites

• Python 3.9+ (use py command on Windows)
• Node.js 18.17+

1. Clone the repo

git clone https://github.com/ORNOB-083/AI-Lab-Project-Puzzle-Solver.git
cd AI-Lab-Project-Puzzle-Solver

2. Set up the backend

cd backend (using cmd)

py -m venv venv
venv\Scripts\activate        # Windows
# source venv/bin/activate   # Mac/Linux

Then

pip install -r requirements.txt
uvicorn main:app --reload --port 8000

• Backend runs at: http://127.0.0.1:8000
• API docs: http://127.0.0.1:8000/docs

3. Set up the frontend

cd frontend
npm install

Create a .env.local file inside the frontend folder:

• text

NEXT_PUBLIC_API_URL=http://127.0.0.1:8000

Then run:

npm run dev

Project Screenshot

📄 License

© 2026 team crazy4x Vibes. All rights reserved.
This project is licensed under the MIT License – see the LICENSE file for details.