Based Puzzles is now live!
🔗 https://based-puzzles.vercel.app/
The ultimate puzzle gaming experience built on Base blockchain. Challenge yourself with Sudoku and crypto-themed Crosswords, compete on leaderboards, and enjoy seamless Web3 integration. A modern, responsive puzzle app designed for the Base ecosystem with sleek design and addictive gameplay.
- Sudoku: Classic 9×9 grid with multiple difficulty levels
- Crossword: Base/crypto-themed clues and puzzles
- Daily Challenges: New puzzles every day to keep you coming back
- Leaderboards: Compete with friends and global players
- Personal Stats: Track your progress, streaks, and achievements
- Timed Mode: Race against the clock for extra challenge
- Dark/Light Theme: Automatic theme switching with manual toggle
- Responsive Design: Perfect on desktop, tablet, and mobile
- Keyboard Navigation: Full keyboard support for power users
- Local Persistence: Your progress saves automatically
- Modern Stack: React 19, TypeScript, Tailwind CSS, Vite
- Performance: Optimized with Vite for lightning-fast builds
- Accessibility: ARIA labels and keyboard navigation
- Type Safety: Full TypeScript coverage
- Frontend: React 19, TypeScript
- Styling: Tailwind CSS with custom design system
- Build Tool: Vite 6
- Icons: Lucide React
- UI Components: Radix UI primitives
- State Management: React Query for server state
- Routing: Wouter (lightweight React router)
- Forms: React Hook Form with Zod validation
The application follows a modular architecture designed for scalability and maintainability.
graph TD
A[User Interface] --> B[React App]
B --> C[Game Modes]
C --> D[Sudoku Mode]
C --> E[Crossword Mode]
B --> F[Leaderboards & Stats]
B --> G[Profile Management]
B --> H[Wallet Integration]
H --> I[Base Blockchain]
D --> J[Sudoku Logic]
E --> K[Crossword Logic]
F --> L[Data Persistence]
G --> M[User Authentication]
I --> N[Smart Contracts]
N --> O[Transaction Handling]
L --> P[Local Storage]
L --> Q[Backend API]
- Components: Modular UI components organized by feature (sudoku, crossword, ui primitives)
- Hooks: Custom React hooks for game logic, data fetching, and state management
- Lib: Utility functions, game algorithms, and configuration
- Pages: Route-based page components for navigation
- User interactions trigger state updates via React hooks
- Game logic is handled in custom hooks with local state persistence
- Blockchain integration manages wallet connections and transactions
- Leaderboards and stats are fetched from backend services
This frontend application integrates with a backend service for persistent data storage and blockchain interactions. For detailed backend integration documentation, see backend-integration.md.
- Leaderboard Data: Fetched from backend API for global rankings
- User Statistics: Stored and retrieved from backend for cross-device sync
- Blockchain Transactions: Handled through wallet integration for rewards and payments
- Daily Challenges: Generated and validated server-side for fairness
- Node.js 18+ and npm/pnpm
- Git
-
Clone the repository
git clone https://github.com/yourusername/based-puzzles.git cd based-puzzles -
Install dependencies
npm install # or pnpm install -
Start development server
npm run dev # or pnpm dev -
Open your browser Navigate to
http://localhost:5173
npm run build
npm run previewThe application is configured for deployment on Vercel with the included vercel.json configuration. The build output is optimized for static hosting.
- Connect your repository to Vercel
- Configure environment variables if needed
- Deploy automatically on push to main branch
- Build the project:
npm run build - Serve the
distfolder on any static host (Netlify, GitHub Pages, etc.)
- Click a cell and use your keyboard (1-9) or the number pad
- Use arrow keys to navigate
- Check your solution or get hints when stuck
- Click a cell and type letters
- Use arrow keys or click clues to navigate
- Across and down clues guide your solving
- New puzzles available every day
- Compete on daily leaderboards
- Build your solving streak!
src/
├── components/ # Reusable UI components
│ ├── ui/ # Base UI primitives
│ ├── sudoku/ # Sudoku-specific components
│ ├── crossword/ # Crossword-specific components
│ └── modes/ # Game mode wrappers
├── hooks/ # Custom React hooks
├── lib/ # Utilities and game logic
├── pages/ # Route components
└── types.ts # TypeScript type definitions
We welcome contributions from the community! Whether you're fixing bugs, adding features, or improving documentation, your help is appreciated.
- Fork the repository on GitHub
- Clone your fork locally:
git clone https://github.com/yourusername/based-puzzles.git - Create a feature branch:
git checkout -b feature/your-feature-name - Install dependencies:
npm installorpnpm install - Start development:
npm run dev
- Make your changes following the guidelines below
- Test your changes thoroughly
- Commit your changes:
git commit -m 'feat: add your feature description' - Push to your branch:
git push origin feature/your-feature-name - Open a Pull Request with a clear description of your changes
- Code Style: Follow the existing TypeScript and React patterns
- TypeScript: Use TypeScript for all new code with proper type annotations
- Testing: Add unit tests for new features and ensure existing tests pass
- Documentation: Update README and inline comments as needed
- Commits: Use conventional commit format (feat, fix, docs, style, refactor, test, chore)
- Pull Requests: Provide clear descriptions and link related issues
- Bug fixes and performance improvements
- New puzzle types or game modes
- UI/UX enhancements
- Accessibility improvements
- Documentation updates
- Test coverage expansion
This project is licensed under the MIT License - see the LICENSE file for details.
This project is built for the Base ecosystem and draws inspiration from classic puzzle games. Special thanks to:
- The Base community for their innovative blockchain platform
- Open-source contributors to React, TypeScript, and related libraries
- The puzzle game community for timeless entertainment concepts
Happy puzzling!
Built on Base