https://github.com/urdadx/bundy-offline
An offline first wordsearch puzzle adventure game
https://github.com/urdadx/bundy-offline
neon offline-first powersync
Last synced: about 2 months ago
JSON representation
An offline first wordsearch puzzle adventure game
- Host: GitHub
- URL: https://github.com/urdadx/bundy-offline
- Owner: urdadx
- Created: 2026-03-19T20:54:06.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2026-03-20T10:26:06.000Z (2 months ago)
- Last Synced: 2026-03-20T13:45:20.501Z (2 months ago)
- Topics: neon, offline-first, powersync
- Language: TypeScript
- Homepage: https://bundylocal.urdadx.com
- Size: 34.3 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Bundy
An educational word search puzzle adventure game. Explore different worlds, complete challenging levels, and learn interesting facts as you play. Play career mode or invite friends to play together in real-time.
## Overview
Bundy is word search game designed with an "offline-first" philosophy. Players journey through themed worlds solving puzzles that get progressively more difficult. The game seamlessly syncs your progress across devices when online while remaining fully functional without an internet connection.
### Key Features
- **Themed Worlds**: Explore "Meadow", "Relic", "Volcano", "Cyber", "Void", and "Malyka", each with its own visual style and unique word sets.
- **Career Mode**: Unlock new worlds by gaining XP and completing stages.
- **AI-Powered Learning**: After every completed stage, the user can generate "Fun Fact" agent that provides unique, educational insights related to the current theme using the Mastra AI agent.
- **Real-time Multiplayer**: Challenge friends to puzzle battles with synchronized moves and live health bars.
- **Progress Sync**: Powered by PowerSync to ensure your stats, XP, and unlocks are never lost, even if you switch devices or go offline.
## Offline-First Philosophy
This project is built to work anywhere, regardless of connectivity.
- **Local-First Data**: All player data (XP, world progress, shop items, inventory) is stored in a local SQLite database within your browser (OPFS).
- **PowerSync Integration**: We use PowerSync to maintain a real-time sync stream between the local database and our cloud Postgres (Neon). This allows for:
- Instant UI updates (no loading spinners for local data)
- Seamless offline play with background reconciliation
- Conflict-free multiplayer state management
- **PWA Ready**: Optimized as a Progressive Web App for a native-like experience on mobile and desktop, including offline asset caching via service workers.
## AI Integration with Mastra
Bundy leverages the **Mastra** framework to power its intelligent features:
- **Fun Fact Agent**: Located in `apps/server/ai/index.ts`, this agent uses `gpt-4o-mini` to generate educational facts based on the current stage theme.
## How to test
- Create an account while online and complete a stage.
- Visit all the pages to load the images and other assets
- Turn off your internet, and refresh
- You will be able to continue playing offline, no data loss
- Your data will be synced automatically once you connect back to the internet
.
## Built with
- **TypeScript** - For type safety and improved developer experience
- **TanStack Router** - File-based routing with full type safety
- **TailwindCSS** - Utility-first CSS for rapid UI development
- **PowerSync** - Real-time local-to-cloud sync for offline-first capabilities
- **Mastra** - AI agent orchestration for dynamic fact generation
- **Better Auth** - Secure, extensible authentication
- **Hono** - Lightweight, performant server framework
- **Bun** - High-speed runtime environment
- **Drizzle** - TypeScript-first ORM for backend schema management
- **Neon** - Serverless Postgres for the cloud-side storage
## Getting Started
First, install the dependencies:
```bash
pnpm install
```
## Database Setup
This project uses Neon with Drizzle ORM.
1. Make sure you have a Neon connection string set up.
2. Apply the schema to your database:
```bash
pnpm run db:push
```
Then, run the development server:
```bash
pnpm run dev
```
Open [http://localhost:3001](http://localhost:3001) in your browser to see the web application.
The API is running at [http://localhost:3000](http://localhost:3000).
The web socket API is running at [http://localhost:3003](http://localhost:3003).
For better observability, I recommend you run each service seperately. Check the [Available Scripts](#available-scripts) section below for the necessary scripts.
## Project Structure
```
bundy/
├── apps/
│ ├── web/ # Frontend application (React + TanStack Router)
│ └── server/ # Backend API (Hono, TRPC, Bun)
├── packages/
│ ├── api/ # API layer / business logic
│ └── db/ # Database schema & queries
│ └── auth # Authentication
│ └── env # Environment variables
```
## Available Scripts
- `pnpm run dev`: Start all applications in development mode
- `pnpm run build`: Build all applications
- `pnpm run dev:web`: Start only the web application
- `pnpm run dev:ws`: Start only the websocket application.
- `pnpm run dev:server`: Start only the server
- `pnpm run check-types`: Check TypeScript types across all apps
- `pnpm run db:push`: Push schema changes to database
- `pnpm run db:studio`: Open database studio UI
- `pnpm run check`: Run Oxlint and Oxfmt
### Deployment
For detailed deployment instructions—including Docker, Dokploy, and VPS setup—see the [DEPLOYMENT.md](./DEPLOYMENT.md) file.
More deployment platforms will be supported soon.
## Contribution
All contributions are welcomed. Kindly open an issue or submit a PR request
# bundy-offline