Convert Wheelgen to Farcaster mini-app

.env.example

@@ -0,0 +1,18 @@
+# Vercel Postgres (automatically provided by Vercel)
+POSTGRES_URL=
+POSTGRES_PRISMA_URL=
+POSTGRES_URL_NON_POOLING=
+POSTGRES_USER=
+POSTGRES_HOST=
+POSTGRES_PASSWORD=
+POSTGRES_DATABASE=
+
+# Farcaster Account Association
+# Generate these at https://warpcast.com/~/developers/mini-apps
+FARCASTER_HEADER=
+FARCASTER_PAYLOAD=
+FARCASTER_SIGNATURE=
+FARCASTER_APP_FID=
+
+# App Configuration
+NEXT_PUBLIC_APP_URL=https://wheelgen.app

FARCASTER_MINIAPP_SETUP.md

@@ -0,0 +1,329 @@
+# WheelGen Farcaster Mini-App Setup Guide
+
+## Overview
+
+WheelGen has been transformed into a Farcaster mini-app with the following features:
+- 🎨 Create generative art with p5.js
+- 🖼️ Gallery to browse community artworks
+- 🚀 Publish artworks to Farcaster feed
+- 🔗 Shareable artwork embeds
+- 👤 Farcaster authentication
+
+## Architecture
+
+### Frontend
+- **Framework**: Vite + SolidJS
+- **Canvas**: p5.js
+- **SDK**: @farcaster/frame-sdk
+- **Routing**: Custom client-side router
+
+### Backend
+- **Platform**: Vercel Serverless Functions
+- **Database**: PostgreSQL (Vercel Postgres)
+- **API**: RESTful endpoints in `/api`
+
+### Routes
+- `/` or `/create` - Art creation interface
+- `/gallery` - Browse community artworks
+- `/art/:id` - View individual artwork (with embeds)
+
+## Prerequisites
+
+- Node.js 22.11.0 or higher
+- pnpm (or npm)
+- Vercel account
+- Farcaster account for app registration
+
+## Local Development Setup
+
+### 1. Install Dependencies
+
+```bash
+pnpm install
+```
+
+### 2. Set Up Database
+
+Create a local PostgreSQL database or use Vercel Postgres for development:
+
+```bash
+# Using Vercel Postgres
+vercel env pull .env.local
+```
+
+Or manually create `.env.local`:
+
+```env
+POSTGRES_URL=postgresql://...
+```
+
+### 3. Run Database Migrations
+
+```bash
+# Connect to your database and run
+psql $POSTGRES_URL < db/schema.sql
+```
+
+### 4. Start Development Server
+
+```bash
+pnpm dev
+```
+
+The app will be available at `http://localhost:5173`
+
+**Note**: Farcaster SDK features will use mock data in development mode outside of a Farcaster client.
+
+## Deployment to Vercel
+
+### 1. Connect to Vercel
+
+```bash
+vercel link
+```
+
+### 2. Set Up Vercel Postgres
+
+```bash
+# Create Postgres database in Vercel dashboard
+# Then pull environment variables
+vercel env pull
+```
+
+### 3. Run Database Migrations
+
+```bash
+# Get production database URL from Vercel dashboard
+# Run migrations
+psql $POSTGRES_URL < db/schema.sql
+```
+
+### 4. Configure Environment Variables
+
+Set these in your Vercel project settings:
+
+**Required:**
+- `POSTGRES_URL` - Auto-configured by Vercel Postgres
+- `FARCASTER_HEADER` - From Farcaster developer portal
+- `FARCASTER_PAYLOAD` - From Farcaster developer portal
+- `FARCASTER_SIGNATURE` - From Farcaster developer portal
+- `FARCASTER_APP_FID` - Your app's FID
+
+**Optional:**
+- `NEXT_PUBLIC_APP_URL` - Your production URL (default: uses request host)
+
+### 5. Deploy
+
+```bash
+vercel --prod
+```
+
+## Registering Your Mini-App with Farcaster
+
+### 1. Generate Account Association
+
+Visit [Warpcast Developer Portal](https://warpcast.com/~/developers/mini-apps) and:
+
+1. Sign in with your Farcaster account
+2. Create a new mini-app
+3. Enter your domain (e.g., `wheelgen.app`)
+4. Generate account association signature
+
+You'll receive three values:
+- Header
+- Payload
+- Signature
+
+### 2. Update Environment Variables
+
+Add these to your Vercel environment variables:
+
+```env
+FARCASTER_HEADER=eyJ...
+FARCASTER_PAYLOAD=eyJ...
+FARCASTER_SIGNATURE=0x...
+FARCASTER_APP_FID=123456
+```
+
+### 3. Verify Manifest
+
+Your app will serve the manifest at:
+```
+https://your-domain.com/.well-known/farcaster.json
+```
+
+Verify it's accessible and contains your account association.
+
+### 4. Test in Farcaster Client
+
+1. Open Warpcast or another Farcaster client
+2. Navigate to your app URL
+3. The app should load with Farcaster SDK ready
+4. Create and publish an artwork
+5. Share the artwork URL in a cast
+
+## API Endpoints
+
+### Artworks
+
+**Save Artwork**
+```
+POST /api/artworks/save
+Headers: Authorization: Bearer <token>
+Body: { title?, data, thumbnailDataUrl }
+```
+
+**List Artworks**
+```
+GET /api/artworks/list?published=true&limit=20&offset=0
+```
+
+**Get Artwork**
+```
+GET /api/artworks/:id
+```
+
+**Publish Artwork**
+```
+POST /api/artworks/publish
+Headers: Authorization: Bearer <token>
+Body: { id }
+```
+
+**Delete Artwork**
+```
+DELETE /api/artworks/:id
+Headers: Authorization: Bearer <token>
+```
+
+### Manifest
+
+**Farcaster Manifest**
+```
+GET /.well-known/farcaster.json
+```
+
+## Database Schema
+
+### Users Table
+- `fid` (BIGINT, PRIMARY KEY) - Farcaster user ID
+- `username` (VARCHAR)
+- `display_name` (VARCHAR)
+- `pfp_url` (TEXT)
+- `bio` (TEXT)
+- Timestamps
+
+### Artworks Table
+- `id` (UUID, PRIMARY KEY)
+- `user_fid` (BIGINT, FOREIGN KEY)
+- `title` (VARCHAR)
+- `data` (JSONB) - Serialized artwork state
+- `thumbnail_data_url` (TEXT) - Base64 thumbnail
+- `published` (BOOLEAN)
+- `published_at` (TIMESTAMP)
+- `views` (INTEGER)
+- Timestamps
+
+## Sharing Artworks on Farcaster
+
+### How It Works
+
+1. User creates artwork in `/create`
+2. User saves artwork via "Publish" tab
+3. User publishes artwork to gallery
+4. Share URL is generated: `/art/:id`
+5. When shared on Farcaster, the embed endpoint serves meta tags
+6. Farcaster renders rich card with thumbnail and "Create Your Own" button
+7. Clicking opens the mini-app
+
+### Embed Strategy
+
+Artwork pages serve special meta tags:
+- `fc:miniapp` - Mini-app embed metadata
+- `fc:frame` - Backward compatibility
+- Open Graph tags for general sharing
+
+The embed endpoint (`/api/artworks/embed/:id`) serves a lightweight HTML page with all necessary meta tags, then redirects to the main app.
+
+## Testing
+
+### Local Testing
+
+```bash
+# Run development server
+pnpm dev
+
+# Test API endpoints
+curl http://localhost:5173/api/artworks/list?published=true
+```
+
+### Testing in Farcaster
+
+1. Deploy to production
+2. Use Warpcast's mini-app preview feature
+3. Share artwork URL in a test cast
+4. Verify embed renders correctly
+
+## Troubleshooting
+
+### SDK Not Loading
+
+- Ensure Node.js version is 22.11.0+
+- Check browser console for errors
+- Verify you're accessing from a Farcaster client
+
+### Database Connection Errors
+
+- Verify `POSTGRES_URL` is set
+- Check Vercel Postgres is active
+- Ensure migrations have run
+
+### Manifest Not Found
+
+- Check `/.well-known/farcaster.json` is accessible
+- Verify Vercel routing in `vercel.json`
+- Check environment variables are set
+
+### Artwork Embeds Not Showing
+
+- Verify artwork is published (`published=true`)
+- Check embed endpoint: `/api/artworks/embed/:id`
+- Test Open Graph tags with validators
+
+## Next Steps
+
+### Planned Features
+
+- [ ] User profiles with artwork collections
+- [ ] Likes and comments on artworks
+- [ ] NFT minting integration
+- [ ] Advanced filtering and search
+- [ ] Collaborative artworks
+- [ ] Animation and GIF export
+- [ ] Onchain artwork verification
+
+### Onchain Integration
+
+Future versions will include:
+- Mint artworks as NFTs on Base
+- Onchain gallery and ownership
+- Creator royalties
+- Provenance tracking
+
+## Resources
+
+- [Farcaster Mini-Apps Docs](https://miniapps.farcaster.xyz)
+- [Warpcast Developer Portal](https://warpcast.com/~/developers/mini-apps)
+- [Vercel Documentation](https://vercel.com/docs)
+- [SolidJS Documentation](https://www.solidjs.com)
+- [p5.js Reference](https://p5js.org/reference/)
+
+## Support
+
+For issues and questions:
+- GitHub Issues: [wheelgen/issues](https://github.com/yourusername/wheelgen/issues)
+- Farcaster: Message the WheelGen team on Warpcast
+
+## License
+
+MIT License - see LICENSE file for details