# Suno Gamez - Music Minigames Platform

A production-grade platform for interactive music minigames built with Next.js, TypeScript, Tailwind CSS, and Convex.

## Features

- **Discovery Feed**: Infinitely scrollable feed with lazy-loaded, sandboxed iframes
- **Game Pages**: Dedicated pages for each game with full details
- **Secure Embedding**: Strict iframe sandboxing with postMessage communication
- **Real-time Data**: Powered by Convex for instant updates
- **TypeScript**: Full type safety throughout the application
- **Responsive Design**: Tailwind CSS for a beautiful, mobile-first UI

## Tech Stack

- **Framework**: Next.js 15 (App Router)
- **Language**: TypeScript
- **Styling**: Tailwind CSS
- **Backend**: Convex (serverless backend)
- **Authentication**: Convex Auth (to be configured)

## Getting Started

### Prerequisites

- Node.js 18+ and npm
- A Convex account (sign up at [convex.dev](https://convex.dev))

### Installation

1. Clone the repository:
   ```bash
   git clone <your-repo-url>
   cd suno-gamez
   ```

2. Install dependencies:
   ```bash
   npm install
   ```

3. Set up Convex:
   ```bash
   npx convex dev
   ```
   This will:
   - Create a new Convex project (if needed)
   - Generate your `.env.local` with `NEXT_PUBLIC_CONVEX_URL`
   - Start the Convex development server
   - Generate TypeScript types in `convex/_generated/`

4. Start the Next.js development server (in a new terminal):
   ```bash
   npm run dev
   ```

5. Open [http://localhost:3000](http://localhost:3000) in your browser

## Data Model

### Tables

- **creators**: Game creators/artists with handle, display name, avatar, bio
- **games**: Minigames with metadata, embed URLs, tags, visibility, stats
- **runs**: Game session tracking with scores and player data

## Seeding Games

Use the Convex dashboard or create a seed script to add games:

```typescript
// In the Convex dashboard, run this mutation:
api.admin.seedGame({
  title: "Rhythm Racer",
  slug: "rhythm-racer",
  srcUrl: "https://example.com/games/rhythm-racer",
  runtime: "external",
  coverUrl: "https://example.com/covers/rhythm-racer.jpg",
  description: "Race to the beat!",
  tags: ["rhythm", "racing", "fast-paced"]
})
```

## Project Structure

```
suno-gamez/
├── app/                    # Next.js App Router
│   ├── game/[slug]/       # Individual game pages
│   ├── layout.tsx         # Root layout with ConvexProvider
│   ├── page.tsx           # Home feed page
│   └── globals.css        # Global styles
├── components/            # React components
│   └── ConvexClientProvider.tsx
├── convex/               # Convex backend
│   ├── schema.ts         # Database schema
│   ├── games.ts          # Game queries/mutations
│   ├── gamesBySlug.ts    # Slug lookup query
│   └── admin.ts          # Admin utilities
├── lib/                  # Utilities
│   ├── types.ts          # TypeScript types
│   └── utils.ts          # Helper functions
└── public/               # Static assets
    └── games/            # Self-hosted games (optional)
```

## Iframe Security

Games are embedded with strict sandboxing:

```typescript
sandbox="allow-scripts allow-same-origin allow-pointer-lock allow-popups-to-escape-sandbox"
allow="gamepad *; accelerometer *; autoplay *; midi *; clipboard-read *; clipboard-write *"
```

## PostMessage API

### From Game to Host

```javascript
// In your minigame iframe
window.parent?.postMessage({
  type: "game:start",
  slug: "your-game-slug"
}, "*");

window.parent?.postMessage({
  type: "game:score",
  slug: "your-game-slug",
  score: 1000
}, "*");
```

### From Host to Game

```javascript
// Host can send commands to games
iframe.contentWindow?.postMessage({
  type: "host:pause"
}, "*");
```

## Hosting Games

### Option A: External URLs
Upload your game to any static host and provide the URL.

### Option B: Vercel Static (Recommended)
Place your game files in `public/games/<slug>/index.html` and set:
```typescript
runtime: "vercel-static"
srcUrl: "/games/<slug>/index.html"
```

## Deployment

### Deploy to Vercel

1. Push your code to GitHub
2. Import your repository in Vercel
3. Vercel will auto-detect Next.js
4. Add environment variables:
   - `NEXT_PUBLIC_CONVEX_URL` (from your Convex dashboard)
5. Deploy!

### Deploy Convex to Production

```bash
npx convex deploy
```

Update your Vercel environment variables with the production Convex URL.

## Future Enhancements

- [ ] Convex Auth integration
- [ ] User profiles and saved games
- [ ] Creator dashboards
- [ ] Analytics and leaderboards
- [ ] AI-powered game generation from prompts
- [ ] Search and filtering
- [ ] Social features (comments, shares)

## License

MIT

## Support

For issues and questions:
- GitHub Issues: [your-repo]/issues
- Convex Discord: [discord.gg/convex](https://discord.gg/convex)
# interact-hack