A Next.js web application that uses AI to analyze memes and explain their pop culture references. Upload a meme, and discover the movie, TV show, or cultural reference behind it, complete with detailed explanations, clips, and cultural context.

• AI-Powered Meme Analysis: Upload any meme and get instant explanations using Perplexity's vision-capable AI
• Pop Culture Database: Automatic matching with TMDB to fetch movie/TV show details, trailers, and clips
• Cultural Lore: Dive deep into awards, cultural impact, trivia, and critical reception
• Similar Movies: Discover similar movies and shows
• Explore Page: Browse through a curated collection of analyzed memes

• Framework: Next.js 15 with App Router
• Styling: Tailwind CSS 4
• AI: Perplexity AI (vision + grounded search)
• Movie Data: TMDB (The Movie Database) API
• Storage: Vercel Blob (images) + Vercel KV (metadata)
• Deployment: Vercel

Before you begin, ensure you have:

• Node.js 18.17+ and npm (or yarn/pnpm)
• Git for version control
• API keys from:
  1. Perplexity AI
  2. TMDB
• (Optional) Vercel account for deploying and using Blob/KV storage in production

git clone <repository-url>
cd perplexity-hack

npm install

1. Copy the example environment file:

   cp .env.example .env.local

2. Open .env.local and add your API keys:

   # Required: Perplexity API Key
   PERPLEXITY_API_KEY=your_perplexity_api_key_here
   
   # Required: TMDB API Key
   TMDB_API_KEY=your_tmdb_api_key_here
   
   # Required: App URL
   NEXT_PUBLIC_APP_URL=http://localhost:3000
   
   # Optional: Vercel Blob Storage (for production)
   BLOB_READ_WRITE_TOKEN=your_blob_token_here
   
   # Optional: Vercel KV Storage (for production)
   KV_URL=your_kv_url_here
   KV_REST_API_URL=your_kv_rest_api_url_here
   KV_REST_API_TOKEN=your_kv_rest_api_token_here
   KV_REST_API_READ_ONLY_TOKEN=your_kv_rest_api_read_only_token_here

For production deployment and cloud storage:

npm i -g vercel
vercel link
vercel env pull

npm run dev

Open http://localhost:3000 in your browser.

src/
├── app/
│   ├── api/                    # API routes
│   │   ├── analyze-meme/       # Upload and analyze memes
│   │   ├── explore/            # Browse memes
│   │   ├── meme/[id]/          # Get meme by ID
│   │   └── movie/[id]/         # Movie details, lore, similar movies
│   ├── explore/                # Explore page
│   ├── meme/[id]/              # Meme analysis result page
│   ├── movie/[id]/             # Movie detail pages
│   │   ├── lore/               # Cultural context and awards
│   │   └── similar/            # Similar Movies page
│   ├── layout.tsx              # Root layout
│   └── page.tsx                # Home page with upload
├── components/                 # Reusable React components
│   ├── MemeCard.tsx            # Meme grid item
│   ├── MemeUpload.tsx          # Drag-drop upload component
│   ├── MovieCard.tsx           # Movie information card
│   └── VideoPlayer.tsx         # YouTube embed player
├── lib/                        # Utility functions
│   ├── perplexity.ts           # Perplexity AI integration
│   └── tmdb.ts                 # TMDB API integration
└── types/                      # TypeScript types
    └── index.ts                # Shared type definitions

1. Upload: User uploads a meme image via drag-drop or file picker
2. Analysis: Image is stored in Vercel Blob and sent to Perplexity's vision model
3. Extraction: AI identifies the movie/TV show reference and explains the joke
4. Enrichment: App fetches detailed info from TMDB (posters, trailers, metadata)
5. Storage: Analysis is cached in Vercel KV for fast retrieval
6. Lore: Perplexity provides cultural context, awards, and trivia on demand
7. Discovery: Users can find similar Movies or explore the full collection

• npm run dev - Start development server with Turbopack (faster builds)
• npm run build - Build for production with Turbopack optimization
• npm start - Start production server
• npm run lint - Run ESLint to check code quality

• POST /api/analyze-meme - Upload and analyze a meme
• GET /api/meme/[id] - Get meme analysis by ID
• GET /api/movie/[id] - Get movie/TV show details
• GET /api/movie/[id]/lore - Get cultural context and awards
• GET /api/movie/[id]/similar-memes - Find similar movies
• GET /api/explore - Browse all analyzed memes

"API Key not found" error

• Ensure .env.local exists in the project root
• Verify API keys are set correctly (no quotes or extra spaces)
• Restart the development server after changing environment variables

Port 3000 already in use

npm run dev -- -p 3001

Module not found errors

• Clear node_modules and reinstall:

  rm -rf node_modules package-lock.json
  npm install

Build fails with TypeScript errors

• Check that all environment variables are set
• Run npm run lint to identify code issues

Deploy to Vercel:

1. Push your code to GitHub
2. Import the project in Vercel
3. Add environment variables in Vercel dashboard
4. Enable Vercel Blob storage
5. Enable Vercel KV storage
6. Deploy!

MIT