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

Tournament Manager (Coming Soon)

• Manage Challonge tournaments
• Add/remove participants
• Submit match scores
• Track tournament progress

🔑 API Keys & Configuration

Challonge API

1. Create account at https://challonge.com
2. Get API key from https://challonge.com/settings/developer
3. Add to .env:

   VITE_CHALLONGE_API_KEY=your_key_here
   

Environment Variables

All environment variables must be prefixed with VITE_ to be available in the browser:

# ✅ Correct - Available in browser
VITE_CHALLONGE_API_KEY=abc123

# ❌ Wrong - Not accessible
CHALLONGE_API_KEY=abc123

Access in code:

const apiKey = import.meta.env.VITE_CHALLONGE_API_KEY;

🛠️ Tech Stack

• Vue 3.4 - Progressive JavaScript framework with Composition API
• Vue Router 4 - Official routing library
• Vite 5 - Next generation frontend tooling
• Docker - Containerization
• nginx - Web server for production

📚 Documentation

• PROJECT_PLAN.md - Complete implementation roadmap
• GAMEMASTER_IMPLEMENTATION.md - Gamemaster feature details
• Vue 3 Docs
• Challonge API

🔒 Security Notes

• Never commit .env - Contains sensitive API keys
• Use environment variables - All configs in .env
• Prefix with VITE_ - Required for browser access
• Keep API keys private - Don't share in public repos

🔗 Related Apps

• apps/ - Additional apps accessible at app.pokedex.online

📝 Development Notes

This project uses:

• Vue 3 Composition API with <script setup>
• Vite for fast HMR and optimized builds
• Multi-stage Docker builds for minimal image size
• nginx:alpine for production serving