A full-stack Sudoku web application built with React and Node.js.
- Multiple Difficulty Levels: Easy, Medium, Hard, and Expert
- Interactive Sudoku Board: Click to select cells, keyboard input (1-9, Backspace)
- Smart Validation: Real-time puzzle checking with instant feedback
- Undo System: Revert moves with move history tracking
- Hint System: Get intelligent hints when stuck
- Auto-Save: Automatically saves game progress for logged-in users
- Timer: Track your solving time for each puzzle
- Daily Puzzle: New puzzle generated every day at midnight
- Streak Tracking: Maintain your current and longest solving streaks
- Completion Stats: See how many players completed today's puzzle
- Average Time: Compare your time with community averages
- User Authentication: Secure JWT-based login and registration
- Profile Dashboard: View comprehensive statistics
- Games played and completed
- Current and longest streaks
- Best times for each difficulty level
- Recent game history
- Leaderboard: Top 100 players ranked by games completed and streaks
- Game History: Track all your completed games with scores
- React 18.2.0 - Modern UI library
- React Router DOM 6.20.0 - Client-side routing
- Context API - State management (Auth, Game)
- Axios 1.6.2 - HTTP client
- React Icons 4.12.0 - Icon library
- Node.js - JavaScript runtime
- Express 4.18.2 - Web framework
- MongoDB - NoSQL database
- Mongoose 7.6.0 - MongoDB ODM
- JWT (jsonwebtoken 9.0.2) - Authentication
- bcryptjs 2.4.3 - Password hashing
- nodemon 3.0.1 - Backend auto-reload
- react-scripts 5.0.1 - React development tools
- Node.js (v14 or higher)
- MongoDB (local installation or MongoDB Atlas account)
- npm or yarn
-
Clone the repository
cd c:\Users\jmana\Grid-Master
-
Install Backend Dependencies
cd server npm install -
Install Frontend Dependencies
cd ../client npm install -
Configure Environment Variables
Create
server/.envfile:PORT=5000 MONGO_URI=mongodb://localhost:27017/sudoku-app JWT_SECRET=your_jwt_secret_key_here NODE_ENV=development
-
Start MongoDB
If using local MongoDB:
mongod
Or configure MongoDB Atlas connection string in
.env -
Start the Backend Server
cd server npm run devServer runs on http://localhost:5000
-
Start the Frontend Development Server
cd client npm startReact app opens on http://localhost:3000
Register a new user
{
"username": "player123",
"email": "player@example.com",
"password": "securepassword"
}Login existing user
{
"email": "player@example.com",
"password": "securepassword"
}Get current user (requires authentication)
Generate a new puzzle
{
"difficulty": "medium"
}Validate current puzzle state
{
"gameId": "64f5a1b2c3d4e5f6a7b8c9d0",
"currentState": [[5,3,0,0,7,0,0,0,0], ...]
}Get a hint for the current puzzle
{
"gameId": "64f5a1b2c3d4e5f6a7b8c9d0",
"currentState": [[5,3,0,0,7,0,0,0,0], ...]
}Update game state (auto-save)
{
"currentState": [[5,3,4,6,7,8,9,1,2], ...],
"timeSpent": 420,
"hintsUsed": 2,
"mistakesMade": 1
}Get user's saved games
Get today's daily puzzle
Start today's daily challenge
Get user's streak information
Get current user's statistics
Get top 100 players leaderboard
Get user's game history (last 50 completed games)
Grid-Master/
├── client/ # React frontend
│ ├── public/
│ │ └── index.html
│ ├── src/
│ │ ├── components/ # React components
│ │ │ ├── Navbar.js
│ │ │ ├── PrivateRoute.js
│ │ │ └── SudokuBoard.js
│ │ ├── context/ # Context providers
│ │ │ ├── AuthContext.js
│ │ │ └── GameContext.js
│ │ ├── pages/ # Page components
│ │ │ ├── Home.js
│ │ │ ├── Login.js
│ │ │ ├── Register.js
│ │ │ ├── Play.js
│ │ │ ├── DailyChallenge.js
│ │ │ ├── Leaderboard.js
│ │ │ └── Profile.js
│ │ ├── services/ # API services
│ │ │ └── api.js
│ │ ├── styles/ # CSS files
│ │ ├── App.js
│ │ └── index.js
│ └── package.json
│
├── server/ # Node.js backend
│ ├── src/
│ │ ├── controllers/ # Route controllers
│ │ │ ├── authController.js
│ │ │ ├── puzzleController.js
│ │ │ ├── dailyController.js
│ │ │ └── userController.js
│ │ ├── middleware/ # Express middleware
│ │ │ └── auth.js
│ │ ├── models/ # Mongoose schemas
│ │ │ ├── User.js
│ │ │ ├── Game.js
│ │ │ └── DailyPuzzle.js
│ │ ├── routes/ # API routes
│ │ │ ├── auth.js
│ │ │ ├── puzzle.js
│ │ │ ├── daily.js
│ │ │ └── user.js
│ │ ├── utils/ # Utility functions
│ │ │ └── sudokuGenerator.js
│ │ └── server.js # Express app entry
│ ├── .env
│ └── package.json
│
└── README.md
The application uses a recursive backtracking algorithm to generate valid Sudoku puzzles:
- Fill Grid: Recursively fills empty cells with valid numbers (1-9)
- Validation: Ensures no duplicates in rows, columns, or 3x3 boxes
- Remove Cells: Strategically removes cells based on difficulty
- Easy: 35 cells removed
- Medium: 45 cells removed
- Hard: 52 cells removed
- Expert: 58 cells removed
- Unique Solution: Verifies puzzle has exactly one solution
score = baseDifficulty × timeMultiplier - hintPenalty- Base difficulty: Easy (100), Medium (200), Hard (300), Expert (500)
- Time multiplier: Bonus for fast completion
- Hint penalty: -50 points per hint used
Terminal 1 - Backend:
cd server
npm run devTerminal 2 - Frontend:
cd client
npm startThe app will open at http://localhost:3000
cd client
npm run build- Password Hashing: bcryptjs with salt rounds
- JWT Authentication: Secure token-based auth
- CORS Configuration: Cross-origin resource sharing
- Input Validation: Server-side validation for all inputs
- Protected Routes: Authentication middleware for sensitive endpoints
- Mobile app (React Native)
- Pencil marks / notes feature
- Multiplayer competitions
- Puzzle import/export
- Dark mode
- Sound effects and animations
- Social features (friends, challenges)
- PWA support for offline play
- Achievement system
- Customizable themes
MIT License - feel free to use this project for learning or commercial purposes.
Built with ❤️ using React and Node.js