Pokemon TCG Vending Machine Search

Search and claim cards from the TCG vending machine inventory.

Features

• 🔍 Real-time search powered by Algolia
• 🎴 Card claiming system with Supabase backend
• ⚡ Serverless API routes on Vercel
• ✅ Comprehensive test coverage

Project Structure

/
├── tcg-search/          # React frontend application
│   ├── src/
│   │   ├── components/  # React components (search, carousels, modals, chat)
│   │   ├── utilities/   # Algolia & Supabase client setup
│   │   └── assets/      # Logos and icons
│   ├── api/             # Vercel serverless API routes
│   └── public/          # Static assets
├── data/                # Algolia index management
│   ├── data-files/      # CSV inventory data
│   └── data-utilities/  # Python scripts for indexing
├── vercel.json          # Vercel deployment configuration
└── .vercelignore        # Files excluded from deployment

Prerequisites

Required Accounts

• Algolia - Search service (free tier available)
• Supabase - Database backend (free tier available)
• Vercel - Hosting platform (free tier available)

Local Development Tools

• Node.js 20+ (required by @supabase/supabase-js)

  node --version  # Should be v20.0.0 or higher

• Vercel CLI: npm i -g vercel
• Python 3.x + Poetry (only needed for updating Algolia index)

Tech Stack

• React 18 with Algolia InstantSearch v7
• Supabase JS Client for real-time subscriptions
• Vercel Serverless Functions

Development

Local Development

Run full stack locally (frontend + API):

npm run dev
# or
vercel dev

This starts:

• React dev server at http://localhost:3000
• API routes at http://localhost:3000/api/*

Run frontend only (no API):

cd tcg-search
npm start

Environment Variables

Required for local development (.env in tcg-search/):

# Algolia
REACT_APP_ALGOLIA_APP_ID=your_app_id
REACT_APP_ALGOLIA_API_KEY=your_search_key
REACT_APP_ALGOLIA_INDEX_NAME=your_index_name
REACT_APP_USER_TOKEN=your_user_token

# Supabase
REACT_APP_SUPABASE_URL=https://your-project.supabase.co
REACT_APP_SUPABASE_PUBLISHABLE_KEY=your_publishable_key
SUPABASE_SECRET_KEY=your_secret_key

Testing

cd tcg-search

# Interactive watch mode
npm test

# One-time run with coverage
npm run test:ci

See tcg-search/TESTING.md for detailed testing documentation.

Deployment

First Time Setup

1. Link to Vercel project:

   vercel link

2. Add environment variables in Vercel dashboard:

   • Go to Project Settings → Environment Variables
   • Add all variables from .env (see above)
   • Make sure to add them for all environments (Production, Preview, Development)

Deploy

Deploy from repository root (not tcg-search/):

# Preview deployment
npm run deploy
# or
vercel

# Production deployment
npm run deploy:prod
# or
vercel --prod

The vercel.json configuration handles the mono-repo structure automatically.

What Gets Deployed

• ✅ React frontend (built from tcg-search/)
• ✅ API routes (from api/)
• ✅ Serverless functions configuration
• ❌ Data scripts (excluded via .vercelignore)
• ❌ Tests and coverage (excluded)

Architecture

Frontend (/tcg-search)

• Framework: React 18 with Create React App
• Search: Algolia InstantSearch v7
• Styling: Custom CSS

Backend (/api)

• Platform: Vercel Serverless Functions
• Database: Supabase (Postgres)
• API Routes:
  • POST /api/claims/create - Submit card claim

Security

• Row Level Security (RLS) enabled on Supabase
• Rate limiting: 5 claims per hour per email
• Server-side validation for all inputs

Contributing

1. Create a feature branch: git checkout -b feat/your-feature
2. Make changes and test locally with vercel dev
3. Run tests: cd tcg-search && npm run test:ci
4. Commit with semantic prefixes: feat:, fix:, chore:, etc.
5. Push and create a PR

See .claude/CLAUDE.md for detailed contribution guidelines.

License

Private repository - see LICENSE file for details.