BOOP Web

Word Search Puzzle Generator — From CLI to Cloud

Live Link · Report Bug · Request Feature

---

Features

Puzzle Generation

• Multiple difficulty levels — Easy, Normal, Hard, Very Hard, Nightmare
• Bonus modes — Circular mask puzzles for an extra challenge
• Custom word lists — Upload via file or type manually, grouped by topic
• Custom assets — Upload cover images, backgrounds, and puzzle backgrounds

Interactive Play

• Live word search grid — Click-and-drag to select words, keyboard navigation
• Hint system — Global 30-second cooldown, highlight next unfound word
• Timer — Persists across page refreshes, pause/resume
• Progress persistence — Save and restore game state via localStorage

Download & Share

• PDF puzzle books — Generate multi-puzzle books with covers and backgrounds
• Poster download — Solved grid as a poster-style PNG with word list and solve time
• Web Share API — Share solved puzzles via native share sheet with image attachment

UI/UX

• Dark mode — Automatic system preference detection with manual toggle
• Responsive design — Works on mobile, tablet, and desktop
• Live preview — SVG puzzle preview while configuring
• Loading states — Skeleton screens and animated progress indicators
• Error handling — Dismissible error banners with clear messages
• Accessibility — Keyboard navigation, ARIA labels, focus trapping in modals

Tech Stack

Layer	Technology	Purpose
Backend	FastAPI	REST API framework
	fpdf2	PDF puzzle book generation
	svgwrite	SVG asset rendering
	svglib	SVG to PDF conversion
	reportlab	Advanced PDF layout
	slowapi	Rate limiting
	Uvicorn	ASGI server
Frontend	React 19	UI framework
	React Router 6	Client-side routing
	Axios	HTTP client
	CSS Modules	Component styling
Deployment	Vercel	Frontend hosting
	Hugging Face Spaces	Backend hosting (Docker)
	GitHub Actions	CI/CD pipeline

Quick Start

Prerequisites

• Node.js 18+ and npm
• Python 3.9+ and pip

Setup

# Clone
git clone https://github.com/Muneer320/BOOP-web.git
cd BOOP-web

# Backend
cd Backend
python -m venv venv
source venv/bin/activate   # Windows: venv\Scripts\activate
pip install -r requirements.txt
cd ..

# Frontend
cd frontend
npm install
cd ..

Run

# Terminal 1 — Backend
cd Backend
uvicorn app:app --reload   # → http://localhost:8000

# Terminal 2 — Frontend
cd frontend
npm start                  # → http://localhost:3000

Project Structure

BOOP-web/
├── Backend/                    # FastAPI backend (deployed to HF Spaces)
│   ├── boop/                   # Core puzzle generation logic
│   │   ├── generatePuzzle.py   # Word search grid algorithm
│   │   ├── appendImage.py      # PDF assembly with assets
│   │   ├── rawWordToJSON.py    # Word-list processing
│   │   └── Assets/             # Cover & background images
│   ├── routers/                # API route modules
│   │   ├── files.py            # File upload/download
│   │   ├── generate.py         # Puzzle book generation
│   │   ├── play.py             # Single-puzzle generation
│   │   ├── settings.py         # App configuration
│   │   ├── status.py           # Health check
│   │   ├── templates.py        # Asset templates
│   │   └── words.py            # Word topics
│   ├── app.py                  # Entry point
│   ├── limiter.py              # Rate limit config
│   ├── requirements.txt        # Python dependencies
│   ├── Dockerfile              # HF Space container definition
│   └── README.md               # Backend API docs
├── frontend/                   # React frontend (deployed to Vercel)
│   ├── src/
│   │   ├── components/         # React components
│   │   ├── context/            # React context providers
│   │   ├── hooks/              # Custom hooks (timer, persistence)
│   │   ├── pages/              # Route pages
│   │   ├── services/           # API client (Axios)
│   │   ├── styles/             # Global CSS & variables
│   │   └── assets/             # Images, icons, fonts
│   ├── public/                 # Static files
│   └── package.json
├── .github/                    # CI/CD & HF metadata
│   ├── workflows/deploy.yml    # GitHub Actions deployment
│   ├── HF_README.md            # HF Space landing page
│   └── HF_gitattributes        # HF Xet binary file config
└── README.md                   # You are here

API Documentation

Endpoint	Method	Description
/api/status	GET	Health check
/api/settings	GET	App configuration limits
/api/templates	GET	Available cover/background templates
/api/topics	GET	Word topic categories
/api/topics/{topic}/words	GET	Words for a specific topic
/api/upload	POST	Upload file (image or word list)
/api/files/{file_id}	GET	Retrieve uploaded file
/api/files/{file_id}	DELETE	Delete uploaded file
/api/generate-puzzle	POST	Generate a multi-puzzle PDF book
/api/play/generate	POST	Generate a single playable puzzle

For full request/response schemas, see the Backend README.

Deployment

Automated (GitHub Actions)

Push to main triggers the deploy workflow:

• Backend — Synced to Hugging Face Space via Docker
• Frontend — Deployed to Vercel

Manual

# Frontend
cd frontend
REACT_APP_API_URL=<backend-url> npm run build
npx vercel --prod

# Backend (Docker)
docker build -t boop-backend Backend/
docker run -p 7860:7860 boop-backend

Environment Variables

Variable	Default	Required	Description
REACT_APP_API_URL	—	Yes	Backend API base URL
CORS_ORIGINS	http://localhost:3000	No	Allowed CORS origins (comma-separated)

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

Distributed under the MIT License. See LICENSE for more information.

---

Built with ❤️ by Muneer320