Cauldron2Code

Inspiration

We've all been there: staring at a blank terminal, about to start a new project, and spending the next hour setting up boilerplate—configuring TypeScript, choosing between Next.js or Express, debating Prisma vs Drizzle, copying .env.example files... It's exhausting before you even write your first line of actual code.

Traditional scaffold generators ask you 20 CLI questions in a row. Boring. Forgettable. Not fun.

What if starting a project felt like casting a spell?

For Kiroween, we wanted to resurrect the joy of creation and wrap it in a hauntingly delightful experience. We imagined a witch's workshop where every technology choice becomes an ingredient dropped into a bubbling cauldron. Mix your stack, watch the brew, and—poof—your entire project materializes as a GitHub repository.

What it does

Cauldron2Code is an interactive full-stack scaffold generator with a pixel-art wizard interface.

Here's the magic:

🏚️ Enter the Witch's Workshop - You arrive at a mystical pixel-art environment with a bubbling cauldron at its center

🧪 Choose Your Ingredients - Select technologies through an animated wizard:

Framework potions (Next.js, React, Vue, Angular, Svelte)
Backend cauldrons (Next.js API, Express, Fastify, NestJS)
Database spell books (Prisma, Drizzle, Supabase, MongoDB)
Auth guards (NextAuth, Clerk, Supabase Auth)
Styling decorations (Tailwind, CSS Modules, Styled Components)
Build tools (Vite, Webpack, Auto)
AI enchantments (5 production-ready AI templates)
Deployment runes (Vercel, Railway, Render, Netlify, AWS Amplify)

✨ Watch the Brew - Each choice animates beautifully: selected options fly into the cauldron with arc physics, the cauldron bubbles continuously, and sparkles pulse around the edges

🔮 Review Your Recipe - A summary step shows all your selections before generation

🐙 Push to GitHub - Authenticate with GitHub OAuth and your fully-configured project is pushed directly to a new repository

📚 Deployment Guides - Access interactive, step-by-step deployment tutorials tailored to your specific configuration with progress tracking, troubleshooting sections, and platform comparisons

Behind the scenes, we generate:

Complete project structure (Next.js, React SPA, Fullstack Monorepo, or Express API)
All configuration files (tsconfig, eslint, prettier, tailwind)
Package.json with exact dependencies
Working authentication flows (NextAuth, Clerk, or Supabase)
Database schemas and migrations (Prisma, Drizzle, or MongoDB)
API routes and endpoints (REST, tRPC, or GraphQL)
5 production-ready AI templates with full implementations:
- AI Chatbot with streaming responses
- Document Analyzer with file upload
- Semantic Search with vector embeddings
- Code Assistant with syntax highlighting
- Image Generator with text-to-image
Deployment configs (Vercel, Railway, Render, Docker)
Example components and pages
Comprehensive README, SETUP, and DEPLOYMENT guides

How we built it

Tech Stack

Next.js 16 (App Router) - Framework
TypeScript - Type safety
Tailwind CSS - Styling with pixel-art aesthetic
Zustand - State management with persistence
Custom pixel fonts - Pixelify Sans for authentic retro feel
GitHub OAuth & API - Repository creation and code pushing
Octokit - GitHub API integration

Architecture

Frontend Magic:

🏚️ Pixel Art Background (Dark mystical theme)
       ↓
🧙‍♀️ Wizard Steps (13 conditional steps with animations)
       ↓
🔥 Cauldron Asset (Fixed position, always visible)
       ↓
📦 Option Grids (Clickable tech icons with hover effects)

Animation Pipeline:

User clicks option → Selected state updates
Validation runs → Compatibility rules check
Next button clicked → Flying animation triggers
Selected icon clones and flies in arc to cauldron
Parabolic trajectory with gravity physics (quadratic bezier curve)
Icon scales down and fades as it approaches cauldron
Fade out current step → Navigate to next step → Fade in
Progress bar updates at bottom
Sparkles pulse continuously around cauldron

Backend Generation:

// Core generator architecture
interface ScaffoldConfig {
  projectName: string;
  description: string;
  frontendFramework: 'nextjs' | 'react' | 'vue' | 'angular' | 'svelte';
  backendFramework: 'none' | 'nextjs-api' | 'express' | 'fastify' | 'nestjs';
  buildTool: 'auto' | 'vite' | 'webpack';
  projectStructure: 'nextjs-only' | 'react-spa' | 'fullstack-monorepo' | 'express-api-only';
  auth: 'none' | 'nextauth' | 'clerk' | 'supabase';
  database: 'none' | 'prisma-postgres' | 'drizzle-postgres' | 'supabase' | 'mongodb';
  styling: 'tailwind' | 'css-modules' | 'styled-components';
  aiTemplates: Array<'chatbot' | 'document-analyzer' | 'semantic-search' | 'code-assistant' | 'image-generator'>;
  aiProvider?: 'anthropic' | 'openai' | 'aws-bedrock' | 'gemini';
  deployment: Array<'vercel' | 'railway' | 'render' | 'netlify' | 'aws-amplify'>;
  extras: {
    docker: boolean;
    githubActions: boolean;
    redis: boolean;
    prettier: boolean;
    husky: boolean;
  };
}

// Template system with conditional generation
generateScaffold(config) {
  - Create base project structure based on projectStructure
  - Conditionally add framework-specific files
  - Generate package.json with dependencies
  - Add AI templates if selected (with provider SDK)
  - Create deployment configs based on targets
  - Generate example routes/components
  - Generate comprehensive documentation
  - Push to GitHub via Octokit API
}

Key Technical Achievements:

Smart Compatibility Validation - Real-time rules engine that disables incompatible options:

Express/Fastify/NestJS can't be used with Next.js frontend
Next.js API requires Next.js frontend
Supabase Auth requires Supabase database
NextAuth requires a database
Redis requires a backend
AI templates require Next.js or monorepo structure
Vercel can't deploy standalone Express apps

Conditional Wizard Flow - Steps dynamically show/hide based on selections:

AI Provider step only appears if AI templates are selected
GitHub Auth step skips if already authenticated
Progress bar adjusts to show only visible steps

Persistent Configuration - Zustand with localStorage persistence:

Configuration survives page refreshes
Migration system for config version updates
Auto-cleanup of incompatible selections

GitHub Integration - Complete OAuth flow:

Authenticate with GitHub
Create repository with sanitized names
Push entire scaffold using Octokit
Handle conflicts, rate limits, and errors gracefully
Store repository URL for future reference

Interactive Deployment Guides - Context-aware documentation:

Platform comparison with recommendations
Step-by-step instructions tailored to your config
Progress tracking across page refreshes
Quick Start vs Detailed Guide modes
Export as Markdown or print
Troubleshooting sections
Architecture diagrams with Mermaid
Environment variable detection and validation

Pixel-Perfect Animations - Smooth 60fps performance:

Arc trajectory physics for flying ingredients
Continuous cauldron bubbling
Sparkle pulse effects with staggered timing
Fade transitions between steps
Loading screen with animated cauldron frames
Reduced motion support for accessibility

Development with Kiro

We used Kiro AI IDE's spec-driven development extensively:

Created 5 major specs with requirements, design, and task lists:
- github-direct-push - OAuth and repository creation
- generation-loading-screen - Animated loading states
- option-compatibility-validation - Smart validation engine
- halloween-deployment-guides - Interactive deployment tutorials
- ai-template-ui - AI feature templates
Let Kiro implement boilerplate (API routes, components, state management)
Used supervised mode for critical animations and GitHub integration
Autopilot for repetitive template generation code

Kiro helped us move 3x faster on the scaffold generation engine while we focused on the creative pixel-art experience.

Challenges we ran into

1. Flying Animation Physics

Problem: Making ingredients fly into the cauldron with realistic gravity

Solution: Implemented quadratic bezier curves for parabolic arc, added random horizontal offset, used cubic-bezier easing for acceleration, cloned elements to avoid layout shifts

2. Conditional Wizard Flow

Problem: Steps need to show/hide based on previous selections, but step indices must remain stable

Solution: Separate "absolute step index" from "visible step index", filter steps based on conditional functions, calculate next/previous visible steps dynamically

3. GitHub API Integration

Problem: Creating repos, pushing files, handling OAuth, managing rate limits

Solution: Used Octokit for clean API access, implemented retry logic with exponential backoff, cached repository URLs, handled conflicts by reusing existing repos

4. State Persistence Complexity

Problem: Configuration must persist across page refreshes, but also needs migration for version updates

Solution: Zustand persist middleware with version migrations, separate hydration state to prevent SSR mismatches, auto-adjust dependent fields when selections change

5. Compatibility Validation

Problem: Some tech choices are incompatible (e.g., Express + Next.js), need to prevent invalid combinations

Solution: Centralized compatibility rules engine, real-time evaluation on every config change, disabled states with helpful tooltips explaining why

6. Deployment Guide Context

Problem: Guides need to be tailored to specific configurations, but configs are complex

Solution: Config ID system with URL encoding, localStorage for config storage, automatic cleanup of old configs, detect environment variables from config

Accomplishments that we're proud of

🎨 The Experience

This doesn't feel like a developer tool—it feels like magic. The pixel-art aesthetic, flying ingredients, bubbling cauldron, and smooth animations create a delightful experience. We've had people literally say "whoa" when testing it.

⚡ It Actually Works

We didn't sacrifice functionality for aesthetics. Every generated project:

Installs without errors (bun install works immediately)
Runs immediately (bun dev starts the server)
Has proper TypeScript configs with no errors
Includes working examples and API routes
Deploys successfully to chosen platforms
Contains comprehensive documentation

🏗️ Technical Polish

60fps animations even with multiple simultaneous effects
Smart validation prevents broken configurations
Comprehensive deployment configs that actually work
OAuth flow is seamless with proper error handling
Generated code follows best practices
Accessibility built-in (keyboard navigation, screen readers, reduced motion)

📚 Interactive Deployment Guides

We built a complete deployment guide system:

5 platforms supported (Vercel, Railway, Render, Netlify, AWS Amplify)
Context-aware instructions based on your exact configuration
Progress tracking that persists across sessions
Platform comparison to help you choose
Troubleshooting sections for common issues
Export guides as Markdown
Architecture diagrams with Mermaid

🤖 5 Production-Ready AI Templates

Each AI template includes:

Working API routes with proper error handling
Full UI components with loading states
Support for 4 AI providers (Anthropic, OpenAI, AWS Bedrock, Gemini)
Comprehensive documentation
Environment variable setup
Example usage

🎃 Nailed the Theme

This screams Halloween/Kiroween. Pixel-art witch's workshop, bubbling cauldron, mystical ingredients, flying animations—while remaining professional enough for actual use.

🚀 Speed of Development

Built in ~2 weeks using Kiro's spec-driven development. The structured approach (requirements → design → tasks) kept us organized and moving fast.

What we learned

Technical Learnings

Zustand > Redux for this use case - Less boilerplate, cleaner code, built-in persistence
Conditional rendering is tricky - Separating absolute vs visible indices was key
Animation performance matters - Using transform and opacity only, GPU acceleration, staggered timing
GitHub API is well-designed - Octokit made OAuth and repo creation straightforward
Template generation is hard - Ensuring every combination works required extensive testing
Compatibility rules need centralization - Scattered validation logic becomes unmaintainable

Design Learnings

Animation tells the story - Every interaction reinforces the "brewing" metaphor
Constraints breed creativity - The wizard interface naturally limits options (no decision paralysis)
Delight > Efficiency - Users spent 30 seconds watching animations they could skip. They loved it.
Pixel art works for dev tools - The retro aesthetic makes configuration fun

Process Learnings

Spec-driven development is a game-changer - Having Kiro work from structured specs kept us organized
Build the fun parts first - Starting with animations kept morale high during boring config work
Test early, test often - Found critical bugs by generating 50+ test projects
Documentation matters - Interactive guides communicate value better than README files

Hackathon Learnings

Theme matters - Committing to the pixel-art witch theme made design decisions easier
Scope creep is real - We cut: sound effects, 3D cauldron, template marketplace, multiplayer brewing
Polish compounds - Small touches (flying animations, sparkles, tooltips) add up to "wow"

What's next for Cauldron2Code

Short-term (Next Month)

🔊 Sound design - Bubbling, splashing, magical whooshes
🎨 More frameworks - Remix, Astro, SvelteKit, Solid
🗄️ More databases - Firebase, PlanetScale, Turso
🤖 More AI templates - RAG systems, AI agents, voice interfaces
📱 Mobile optimization - Simplified UI for phone screens

Medium-term (3-6 Months)

🔧 Custom templates - Save favorite combos
👥 Team scaffolds - Generate monorepos for teams
📦 Plugin system - Community-contributed templates
🎯 Project archetypes - One-click "E-commerce", "SaaS", "Documentation site"
🔗 CI/CD generation - Auto-generate GitHub Actions workflows
💾 Project history - Track all generated projects

Long-term Vision

🏪 Template marketplace - Buy/sell premium scaffolds
🤝 Multiplayer brewing - Collaborate on stack choices in real-time
🎓 Learning mode - Explain why certain combos work well
🔮 Stack analytics - "80% of Next.js users also choose Prisma"
🌍 Localization - Support multiple languages
🎪 More categories - Mobile (React Native, Flutter), Desktop (Electron, Tauri)