Create an adorable creature by learning Polkadot and Ink!
Goal: Make Polkadot fun ~~again
# 1. Install PostgreSQL and create 'monsters' database
# 2. Copy environment template
cp .env.example .env.local
# 3. Configure .env.local with your credentials
# 4. Generate Better Auth secret: openssl rand -hex 32
# 5. Install, migrate, and run
npm install
npm run db:migrate
vercel dev --listen 3004 --yes # Use this for workflow testingVisit http://localhost:3004
Monsters Ink! uses Better Auth for authentication with GitHub OAuth integration.
Why GitHub OAuth? Because AI-powered 3D monster generation is expensive (~$2 per user journey), we require GitHub authentication to prevent abuse and botting. As outlined in our grant application, users must authenticate with a GitHub account that has at least one public repository before accessing AI generation features. This ensures the platform serves legitimate developers while protecting our operational budget.
Generate Auth Secret:
# Generate a secure random secret for BETTER_AUTH_SECRET
openssl rand -hex 32Add the generated secret to your .env.local:
BETTER_AUTH_SECRET=your_generated_secret_hereDatabase Schema:
Better Auth tables (user, session, account, verification) are included in our migration files. Run npm run db:migrate to create them.
GitHub OAuth Setup:
- Create a GitHub OAuth app at https://github.com/settings/developers
- Set Authorization callback URL to:
http://localhost:3004/api/auth/callback/github - Add credentials to
.env.local:GITHUB_CLIENT_ID=your_client_id GITHUB_CLIENT_SECRET=your_client_secret
Authentication is configured in /src/lib/auth.ts and requires no additional setup.
-
PostgreSQL - Install PostgreSQL locally:
# macOS (via Homebrew) brew install postgresql@16 brew services start postgresql@16 # Ubuntu/Debian sudo apt-get install postgresql postgresql-contrib sudo systemctl start postgresql # Windows # Download from https://www.postgresql.org/download/windows/
-
Create Database:
# Connect to PostgreSQL psql postgres # Create database CREATE DATABASE monsters; # Exit psql \q
-
Environment Variables: Copy
.env.exampleto.env.localand configure:cp .env.example .env.local
Edit
.env.localwith your credentials:# Database POSTGRES_URL="postgresql://your_username:your_password@localhost:5432/monsters" # GitHub OAuth (get from https://github.com/settings/developers) GITHUB_CLIENT_ID=your_github_client_id GITHUB_CLIENT_SECRET=your_github_client_secret # Better Auth Secret (generate with: openssl rand -hex 32) BETTER_AUTH_SECRET=your_random_secret_here # AI Services (optional for basic development) OPENAI_API_KEY=your_openai_key FAL_KEY=your_fal_key # S3/MinIO Storage (optional for basic development) S3_ENDPOINT=http://localhost:9000 S3_ACCESS_KEY=minioadmin S3_SECRET_KEY=minioadmin S3_BUCKET=monsters-dev S3_REGION=us-east-1
-
Run Database Migrations:
npm install npm run db:migrate
# Database
npm run db:migrate # Run all database migrations
npm run db:reset # ⚠️ Drop all tables and re-run migrations (destructive!)
npm run db:setup # Alias for db:migrate
# Development
vercel dev --listen 3004 --yes # Start dev server (REQUIRED for workflows)
npm run dev # Alternative: Next.js only (workflows won't work)
npm run build # Build for production
npm start # Start production server
# Workflows
npm run workflow:web # Open workflow debugger UI
# Code Quality
npm run lint # Run ESLint
npm run typecheck # TypeScript type checking
npm run format # Format code with Prettier
# Testing
npm test # Run all unit tests
npm test -- --ui # Run tests with interactive UI
npm test -- --watch # Run tests in watch mode
npm test -- --coverage # Run tests with coverage report
# Storage (needed to generate images)
npm run storage:start # Start local MinIO server for S3-compatible storageThe monster pipeline runs in three stages—prompt → OpenAI image → fal.ai 3D model—with every output persisted to S3 so we never redo completed work. When the status endpoint is polled the API starts background processing and supervises retryable failures.
- OpenAI failures: Rate limits, transient network errors, and 5xx responses retry automatically with staged delays (30s baseline, up to five attempts). Content-policy rejections stop immediately so creators can adjust their prompt, while invalid API keys or exhausted credits are marked non-retryable and surface clear operator messages.
- S3 availability: Upload/download issues—including a missing local MinIO instance—raise
s3_upload_error, attempt up to five retries with spacing, and block downstream steps so we do not pay for 3D conversion without storage. - fal.ai failures: Busy queues and network hiccups retry with longer delays (60–120s, up to ten attempts). Invalid credentials or depleted credits halt the job, prompting human intervention instead of looping.
Each retry stores structured metadata (retryCount, lastRetryAt, suggestedRetryDelay), and the status endpoint now honors those delays so we never tight-loop expensive generations. A safety watchdog only resets stuck jobs after twice the planned delay (minimum two minutes) to recover from crashed workers without spamming providers.
- Platform: Vercel serverless functions
- Architecture: Stateless, auto-scaling serverless functions
- Storage: PostgreSQL + S3/MinIO for files
- Performance Focus: Cold start optimization, bundle size, database efficiency
- Smart Contracts: ink! v6
- Frontend: React/Next.js 15 with Turbopack and Three.js for 3D visualization
- Code Editor: Monaco Editor (ink!/Rust syntax)
- Backend: Next.js API routes (Vercel serverless)
- Workflows: Vercel Workflows for durable task execution
- Database: PostgreSQL with connection pooling
- Authentication: GitHub OAuth integration via Better Auth
- Infrastructure: Docker containers for pop-cli compilation service
- AI Pipeline: OpenAI GPT-Image-1, fal.ai image-to-3D, OpenAI content moderation
- Styling: Tailwind CSS v4
- Animation: Motion library (Framer Motion successor)
Lessons are JSON files in src/content/lessons/. Each lesson contains chapters, each chapter contains steps.
URLs:
- Lessons:
/lesson/[lessonId]/[chapterId]/[stepId] - Lesson Editor:
/lesson-editor(also accessible from/admin)
Key Files:
src/content/lessons/*.json- Lesson contentsrc/lib/lesson-types.ts- TypeScript interfacessrc/lib/lesson-editor-validation.ts- Zod schema validationsrc/components/MonacoCodeEditor.tsx- ink!/Rust code editor
Progress: Stored in PostgreSQL (user_lesson_progress, user_chapter_progress, user_step_progress). APIs at /api/progress/*.
Generation Triggers: Steps with triggersGeneration: true and generationStage: "young" | "adult" trigger monster generation at milestones.
Monster generation is triggered automatically when users complete specific lesson milestones.
- Trigger: Completion of a lesson stage sends a structured
GenerateMonsterRequest(defining physical traits, personality, etc.) to the API. - Prompt Engineering: The API uses
generatePromptFromStructuredDatato securely construct a detailed, optimized AI prompt server-side. - Pipeline Execution: A durable Vercel Workflow is initiated:
- 2D Generation: OpenAI's GPT-Image-1 creates a base 2D sprite from the prompt.
- 3D Conversion: If requested, fal.ai converts the 2D sprite into a
.glb3D model. - Asset Storage: All assets are persisted to S3/MinIO to prevent redundant generation.
- Desktop/laptop/iPad browsers only (mobile not supported)