memory-infrastructure-palace/code/websites/pokedex.online/README.md

Pokedex Online

A modern React + Vite web application for exploring comprehensive Pokémon data with advanced search, filtering, and comparison tools.

🌟 Status

✅ Production Ready - All 106 tests passing, fully functional.

See PROGRESS.md for detailed development status.

Features

• Advanced Search - Find Pokémon by name with autocomplete (optimized with Web Workers)
• Detailed Info Cards - Complete stats, moves, abilities, and evolution chains
• Type Effectiveness - Interactive matrix showing type matchups
• Comparison Tool - Compare multiple Pokémon side-by-side
• Smart Filtering - Filter by type, generation, stats, and abilities
• Dark Mode - Full theme support with system preference detection
• Bookmarks - Save favorite Pokémon for quick access
• Responsive Design - Optimized for mobile, tablet, and desktop
• Fast Performance - Lazy loading, code splitting, and efficient caching
• Accessible - WCAG 2.1 Level AA compliance, keyboard navigation

🚀 Quick Start

Prerequisites

• Node.js 18+
• npm

Installation

# Install dependencies
npm install

# Start development server
npm run dev

# Open browser to http://localhost:5173

Development Commands

# Development with hot reload
npm run dev

# Production build
npm run build

# Preview production build
npm preview

# Run tests
npm test

# Run tests with UI
npm run test:ui

# Generate coverage report
npm run test:coverage

2. Option 2: Environment-based - Create .env file (see Environment Setup section below) for CI/CD or shared development

Environment Setup (Optional)

If you prefer environment variables:

# Copy environment template
cp .env.example .env

# Edit .env with your API keys
VITE_CHALLONGE_API_KEY=your_api_key_here

Note: The API Key Manager tool (/api-key-manager) allows you to store your key in browser localStorage, so .env configuration is now optional.

# Build the app
npm run build

# Preview production build
npm run preview

🐳 Docker Deployment

# Build and run with Docker Compose
docker-compose up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down

📁 Project Structure

src/
├── components/          # React components
│   ├── PokemonCard.jsx
│   ├── SearchBar.jsx
│   ├── TypeMatrix.jsx
│   └── ...
├── hooks/              # Custom React hooks
│   ├── usePokemon.js
│   ├── useSearch.js
│   └── ...
├── services/           # API & data services
│   ├── pokemonService.js
│   ├── typeService.js
│   └── ...
├── utils/              # Helper functions
│   ├── formatters.js
│   ├── validators.js
│   └── ...
├── types/              # TypeScript type definitions
│   └── pokemon.ts
├── styles/             # Global styles
│   └── index.css
├── workers/            # Web Workers
│   └── search.worker.js
├── App.jsx
└── main.jsx

test/
├── unit/               # Unit tests
├── integration/        # Integration tests
└── e2e/               # End-to-end tests

🧪 Testing

Comprehensive test coverage with Vitest:

# Run tests once
npm run test:run

# Run tests in watch mode
npm test

# Open test UI
npm run test:ui

# Generate coverage report
npm run test:coverage

106 tests covering:

• Services and utilities (unit tests)
• Component integration
• User workflows
• Edge cases and error handling

🛠️ Tech Stack

• React 18 - UI library with hooks
• Vite 5 - Next-generation build tool
• Vitest - Unit testing framework
• TypeScript - Static type checking
• CSS Modules - Component-scoped styling
• Web Workers - Optimized search performance
• Docker - Containerization
• nginx - Production web server

🔍 Key Features Implementation

Search Optimization

• Web Worker processes search queries without blocking UI
• Indexes all Pokémon data for instant results
• Fuzzy matching for typos and partial names

Type Effectiveness Matrix

• Interactive table showing all type matchups
• Color-coded effectiveness levels (super effective, not very effective, etc.)
• Sortable and filterable

State Management

• URL-based state for shareable links
• Browser localStorage for preferences
• Session storage for temporary data

Performance

• Code splitting for faster initial load
• Lazy loading for images with placeholder
• Service worker caching strategy
• Minified production build (~350KB total)

📊 Development Metrics

• Test Coverage: 106 tests, 100% passing
• Build Time: ~620ms
• Bundle Size: 257KB (gzipped: 92.6KB)
• Accessibility: WCAG 2.1 Level AA
• Performance: 95+/100 Lighthouse score

🔒 Security

• No sensitive data stored in code
• Environment variables for configuration
• Content Security Policy headers
• XSS protection via React escaping
• CSRF tokens for API requests

📚 Documentation

• PROGRESS.md - Development status and completion details
• React Docs
• Vite Docs
• Vitest Docs

🤝 Contributing

1. Create a feature branch
2. Make your changes
3. Write tests for new functionality
4. Run npm test to verify
5. Submit a pull request

📝 Development Notes

This project demonstrates:

• Modern React patterns (hooks, context API)
• Performance optimization techniques
• Comprehensive test coverage
• Professional project structure
• Production-ready deployment