Pokemon Collection Web App - MVP

A Next.js web application for browsing Pokemon with detailed information, stats, and evolution chains. Built for exploring Pokemon data with an intuitive, responsive interface.

🎯 MVP Features Completed

✅ Pokemon Browsing (Fully Implemented)

• Pokemon List Page (/pokemon)

  • Grid view with responsive layout (2-5 columns based on screen size)
  • Search Pokemon by name
  • Filter by type (all 18 Pokemon types)
  • Paginated loading with "Load More" functionality
  • Loading and error states
  • Empty state handling

• Pokemon Detail Page (/pokemon/[id])

  • High-quality Pokemon artwork
  • Type badges with color coding
  • Height and weight information
  • Abilities display
  • Base stats with visual progress bars
  • Evolution chain visualization
  • Back navigation to list page

• UI Components

  • PokemonCard: Interactive card with hover effects
  • PokemonGrid: Responsive grid layout with pagination
  • PokemonDetail: Comprehensive Pokemon information display
  • EvolutionChain: Visual evolution path with images
  • shadcn/ui components: Badge, Button, Progress, Input

🛠️ Tech Stack

• Frontend: Next.js 14.2 (App Router), React 18.3, TypeScript 5.3
• Styling: Tailwind CSS 3.4, shadcn/ui (Radix UI primitives)
• Data Fetching: SWR for client-side caching
• Backend: Next.js API Routes
• Database: PostgreSQL with Prisma ORM 6.17
• External APIs: PokeAPI integration via pokenode-ts
• Testing: Vitest (unit/integration), Playwright (E2E)
• Icons: Lucide React

📋 Prerequisites

• Node.js 18+ and npm 9+
• PostgreSQL 15+ (or Docker)

🚀 Quick Start

Automated Setup (Fastest)

Run the automated setup script for instant configuration:

./docker-setup.sh

This single command will:

• Start PostgreSQL in Docker
• Install npm dependencies
• Generate Prisma Client
• Push database schema
• Provide next steps for data sync and development

Then just run npm run sync:pokemon and npm run dev!

---

Manual Setup

1. Install Dependencies

npm install

2. Database Setup

Option A: Using Docker Compose (Recommended - Easiest)

Start the PostgreSQL database with a single command:

# Start database in background
docker-compose up -d

# View logs
docker-compose logs -f postgres

# Stop database
docker-compose down

# Stop and remove all data
docker-compose down -v

The database will automatically:

• Create the pokemon_collection database
• Set up user credentials (postgres/postgres)
• Persist data in a Docker volume
• Restart automatically on system reboot

Option B: Using Docker Run

docker run --name pokemon-postgres \
  -e POSTGRES_PASSWORD=postgres \
  -e POSTGRES_DB=pokemon_collection \
  -p 5432:5432 \
  -d postgres:15

Option C: Local PostgreSQL

Create a database named pokemon_collection on your local PostgreSQL instance.

3. Configure Environment Variables

The .env file is already created. Update if needed:

DATABASE_URL="postgresql://postgres:postgres@localhost:5432/pokemon_collection?schema=public"
BETTER_AUTH_SECRET="your-secret-key-here-minimum-32-characters-long-for-security"
BETTER_AUTH_URL="http://localhost:3000"

4. Initialize Database

# Generate Prisma Client
npx prisma generate

# Create database tables
npx prisma db push

5. Sync Pokemon Data

# Sync first 151 Pokemon (Generation 1)
npm run sync:pokemon

# Or sync first 251 Pokemon (Generations 1-2)
npm run sync:pokemon 251

# Or sync all Pokemon (~1025)
npm run sync:pokemon all

This will populate your database with Pokemon data from PokeAPI. The sync includes:

• Pokemon stats, types, and abilities
• Sprite images and official artwork
• Evolution chains

Note: Syncing all Pokemon takes ~10-15 minutes due to rate limiting.

6. Start Development Server

npm run dev

Visit http://localhost:3000 to see the app!

📁 Project Structure

Pokemon2/
├── app/                          # Next.js App Router
│   ├── api/                      # API Routes
│   │   └── pokemon/
│   │       ├── route.ts          # GET /api/pokemon (list)
│   │       └── [id]/route.ts     # GET /api/pokemon/:id (detail)
│   ├── pokemon/
│   │   ├── page.tsx              # Pokemon list page
│   │   └── [id]/page.tsx         # Pokemon detail page
│   ├── layout.tsx                # Root layout
│   ├── page.tsx                  # Homepage
│   └── globals.css               # Global styles
├── components/
│   ├── pokemon/
│   │   ├── pokemon-card.tsx      # Individual Pokemon card
│   │   ├── pokemon-grid.tsx      # Grid with pagination
│   │   ├── pokemon-detail.tsx    # Detailed info display
│   │   └── evolution-chain.tsx   # Evolution visualization
│   └── ui/                       # shadcn/ui components
│       ├── badge.tsx
│       ├── button.tsx
│       ├── progress.tsx
│       └── input.tsx
├── lib/
│   ├── services/
│   │   ├── pokemon.service.ts    # Pokemon business logic
│   │   └── sync/
│   │       └── pokemon-sync.service.ts  # Data sync logic
│   ├── prisma.ts                 # Prisma client singleton
│   └── utils.ts                  # Utility functions
├── prisma/
│   └── schema.prisma             # Database schema
├── scripts/
│   └── sync-pokemon.ts           # Data sync CLI script
└── tests/
    ├── contract/                 # API contract tests
    ├── e2e/                      # E2E tests (Playwright)
    │   └── pokemon-browsing.spec.ts
    └── setup.ts                  # Test configuration

🧪 Testing

The project includes comprehensive test coverage with both unit/integration tests and end-to-end tests.

Unit & Integration Tests

# Run all tests
npm test

# Watch mode
npm run test:watch

# Test coverage
npm run test:coverage

# UI mode
npm run test:ui

# Contract tests only
npm run test:contract

E2E Tests (Playwright)

End-to-end tests verify the complete user experience from browser interaction to API responses.

Prerequisites for E2E tests:

1. Database must be populated: npm run sync:pokemon
2. Development server running (auto-started by Playwright config)

# Run all E2E tests (headless)
npm run test:e2e

# Run with UI mode (recommended for development)
npm run test:e2e:ui

# Run in headed mode (see browser)
npm run test:e2e:headed

# Debug mode (step through tests)
npm run test:e2e:debug

# Run specific test file
npx playwright test pokemon-browsing

# Run specific browser
npx playwright test --project=chromium
npx playwright test --project=firefox

E2E Test Coverage:

• Homepage navigation and links
• Pokemon list page with grid display
• Search functionality (by name)
• Type filtering (all 18 Pokemon types)
• Pagination with "Load More" button
• Pokemon detail pages with stats and evolution chains
• Back navigation
• Performance benchmarks (list <500ms, detail <300ms)
• Responsive behavior (mobile/desktop)
• Accessibility (44px minimum touch targets)
• Error handling (API failures, 404 pages)

Test Reports: After running E2E tests, view detailed HTML reports:

npx playwright show-report

Contract Tests

Contract tests define API behavior before implementation (TDD approach):

# Run specific contract tests
npm run test:pokemon      # Pokemon API tests
npm run test:cards        # Trading Cards API tests
npm run test:collection   # Collection API tests
npm run test:values       # Values API tests
npm run test:auth         # Auth API tests

# Performance tests
npm run test:perf

🎨 Design Features

Accessibility

• All interactive elements meet ≥44px touch target size
• Semantic HTML structure
• ARIA labels where appropriate
• Keyboard navigation support

Performance

• Target: <500ms Pokemon list load, <300ms detail pages
• Server-side caching with revalidation
• Optimized images with Next.js Image component
• Client-side data caching with SWR

Responsive Design

• Mobile-first approach
• 2-5 column grid based on viewport
• Touch-friendly interface
• Optimized for phones, tablets, and desktop

📊 Database Schema

Pokemon Model

model Pokemon {
  id                String    # Pokemon identifier
  name              String    # Pokemon name
  nationalDexNumber Int       # Pokedex number
  types             String[]  # Pokemon types
  height            Int       # Height in decimeters
  weight            Int       # Weight in hectograms
  stats             Json      # Base stats object
  sprites           Json      # Sprite URLs
  abilities         String[]  # Ability names
  evolutionChainId  String?   # Evolution chain reference
  tradingCards      TradingCard[]
}

Evolution Chain Model

model EvolutionChain {
  id      String    # Chain identifier
  chain   Json      # Full evolution tree
  pokemon Pokemon[] # Related Pokemon
}

🔄 API Endpoints

List Pokemon

GET /api/pokemon?limit=20&offset=0&search=pikachu&type=electric

Query Parameters:

• limit (default: 20): Number of results
• offset (default: 0): Pagination offset
• search: Filter by name (case-insensitive)
• type: Filter by Pokemon type

Response:

{
  "data": [
    {
      "id": "pikachu",
      "name": "pikachu",
      "nationalDexNumber": 25,
      "types": ["electric"],
      "sprites": { ... },
      ...
    }
  ],
  "pagination": {
    "total": 1025,
    "limit": 20,
    "offset": 0
  }
}

Get Pokemon by ID

GET /api/pokemon/pikachu
GET /api/pokemon/25

Response:

{
  "id": "pikachu",
  "name": "pikachu",
  "nationalDexNumber": 25,
  "types": ["electric"],
  "height": 4,
  "weight": 60,
  "stats": {
    "hp": 35,
    "attack": 55,
    "defense": 40,
    "special_attack": 50,
    "special_defense": 50,
    "speed": 90
  },
  "abilities": ["static", "lightning-rod"],
  "sprites": { ... },
  "evolutionChain": {
    "id": "10",
    "chain": { ... }
  },
  "evolutionPokemon": { ... }
}

📖 API Documentation

The Pokemon Collection API provides RESTful endpoints for accessing Pokemon data with type-safe validation and comprehensive documentation.

Interactive Documentation: http://localhost:3000/docs

Features:

• OpenAPI 3.0 specification with Swagger UI
• Try-it-out functionality for testing endpoints
• Request/response examples with real data
• Schema validation with Zod
• Performance metrics and caching strategies

Quick Links:

• API Documentation - Complete guide with examples
• OpenAPI Spec (JSON) - Machine-readable specification
• Interactive Docs - Swagger UI interface

Available Endpoints:

• GET /api/pokemon - List Pokemon with pagination, search, and filtering
• GET /api/pokemon/{id} - Get detailed Pokemon information with evolution chain

See API_DOCUMENTATION.md for complete documentation including:

• Detailed endpoint descriptions
• Request/response schemas
• Error handling
• Code examples (JavaScript, Python, curl)
• Performance best practices

✅ Camera-Based Card Scanning (Fully Implemented)

• Camera Capture with mobile and desktop support
• OCR Text Extraction using Tesseract.js for automatic card name detection
• Real-time Progress Tracking with confidence scoring
• Quality Indicators for lighting, focus, and image quality
• File Upload Fallback for unsupported browsers
• Privacy-First: All processing happens locally on your device

See Camera Scanning Documentation for detailed usage guide.

🚧 Coming Soon

These features are planned but not yet implemented:

• Trading Cards: Browse Pokemon TCG cards with prices
• Collection Manager: Track your personal card collection
• Card Values: Real-time market price tracking
• User Authentication: Login and profile management
• Advanced Search: Multiple filters, sorting options
• Favorites: Save favorite Pokemon

🐳 Docker Commands

Database Only (Recommended for Development)

# Start PostgreSQL database
docker-compose up -d

# View database logs
docker-compose logs -f postgres

# Stop database (keeps data)
docker-compose down

# Stop and remove all data
docker-compose down -v

# Check database status
docker-compose ps

Full Stack (Database + Next.js App)

# Build and start both services
docker-compose -f docker-compose.full.yml up -d --build

# View all logs
docker-compose -f docker-compose.full.yml logs -f

# Stop all services
docker-compose -f docker-compose.full.yml down

Note: The full stack setup requires standalone output in next.config.js. For development, use database-only mode and run Next.js locally.

📝 Development Commands

# Setup & Verification
npm run verify       # Verify setup requirements

# Development
npm run dev          # Start dev server
npm run build        # Production build
npm start            # Start production server

# Database
npx prisma generate  # Generate Prisma Client
npx prisma db push   # Push schema to database
npx prisma studio    # Database GUI

# Data Sync
npm run sync:pokemon        # Sync 151 Pokemon
npm run sync:pokemon 251    # Sync 251 Pokemon
npm run sync:pokemon all    # Sync all Pokemon

# Testing
npm test                    # Unit/integration tests
npm run test:watch          # Watch mode
npm run test:coverage       # Coverage report
npm run test:e2e            # E2E tests (Playwright)
npm run test:e2e:ui         # E2E with UI mode
npm run test:e2e:debug      # Debug E2E tests

# Code Quality
npm run lint         # ESLint
npm run type-check   # TypeScript type checking

🔧 Troubleshooting

Having issues getting started? Run the setup verification script:

npm run verify

This will check:

• Node.js and npm versions
• PostgreSQL connection
• Environment variables configuration
• Dependencies installation
• Prisma Client generation
• Database schema and data
• Port availability

The script provides helpful error messages and suggestions for fixing any issues found.

Common Issues

Database Connection Failed

# Check if PostgreSQL is running
docker-compose ps

# Start database if stopped
docker-compose up -d

# Check logs
docker-compose logs postgres

Prisma Client Not Generated

npx prisma generate

Database Schema Missing

npx prisma db push

No Pokemon Data

npm run sync:pokemon

Port 3000 Already in Use

# Use a different port
npm run dev -- -p 3001

# Or stop the existing server
pkill -f "next dev"

E2E Tests Failing

# Ensure database is populated
npm run sync:pokemon

# Ensure dev server can start
npm run dev

# Run tests with UI to debug
npm run test:e2e:ui

🐛 Known Issues

• Database connection required for full functionality (see DATABASE_SETUP.md)
• Evolution chains show only primary evolution path (branches not displayed)
• Performance logging shows warnings during data sync (expected)

📚 Documentation

• API Documentation - Complete REST API guide
• Database Setup Guide
• Prisma Schema
• API Contract Tests
• E2E Tests
• Next.js Documentation
• Playwright Documentation
• Interactive API Docs - Swagger UI

🤝 Contributing

This is a personal project for managing a Pokemon card collection. Built with love for Pokemon fans!

📄 License

This project uses data from PokeAPI, which is a free and open API. Pokemon and Pokemon character names are trademarks of Nintendo.