# 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](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

## 🚀 Local Development

### Prerequisites

- Node.js 20+ 
- npm or yarn
- Challonge API key (get from https://challonge.com/settings/developer)

### Environment Setup

1. **Copy environment template**:
   ```bash
   cp .env.example .env
   ```

2. **Configure your API keys** in `.env`:
   ```bash
   # Required: Get your API key from Challonge
   VITE_CHALLONGE_API_KEY=your_actual_api_key_here
   
   # Optional: Set default tournament for testing
   VITE_DEFAULT_TOURNAMENT_ID=your_tournament_url
   ```

3. **Keep your `.env` file secure**:
   - Never commit `.env` to git (already in `.gitignore`)
   - Use `.env.example` for documentation
   - Share API keys only through secure channels

### Quick Start

```bash
# Install dependencies
npm install

# Start development server WITH backend API:
npm run dev:full

# Or start just the frontend (no backend):
npm run dev

# Open browser to http://localhost:5173
```

**Backend Server**: When running `npm run dev:full`, the OAuth proxy and Gamemaster API start automatically on port 3001.

### Gamemaster API

The Gamemaster API provides access to Pokemon GO gamemaster data from PokeMiners:

```javascript
import { gamemasterClient } from './gamemaster-client.js';

// Get filtered pokemon (base forms + regional variants)
const pokemon = await gamemasterClient.getPokemon();

// Get all forms including costumes and variants
const allForms = await gamemasterClient.getAllForms();

// Get all moves
const moves = await gamemasterClient.getMoves();

// Check what's available
const status = await gamemasterClient.getStatus();
```

**Workflow**:
1. Open the **Gamemaster Manager** at `/gamemaster`
2. Click "Fetch from PokeMiners" to download latest data
3. Click "Process & Break Up Data" to categorize
4. Click "Save All Files to Server" to make available to all apps
5. Other apps can now access via the GamemasterClient

See [GAMEMASTER_API.md](GAMEMASTER_API.md) for full documentation and examples.

**API Key Setup** (two options):
1. **Option 1: UI-based (Recommended)** - Use the API Key Manager tool at `/api-key-manager` to store your key locally in the browser
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:

```bash
# 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.

```bash
# Build the app
npm run build

# Preview production build
npm run preview
```

## 🐳 Docker Deployment

### Build and Run Locally

```bash
# Build the image
docker build -t pokedex-online .

# Run the container
docker run -d -p 8080:80 --name pokedex-online pokedex-online

# View in browser
open http://localhost:8080
```

### Using Docker Compose

```bash
# Start the service
docker-compose up -d

# Stop the service
docker-compose down

# View logs
docker-compose logs -f
```

## 📦 Automated Deployment

Deploy to Synology NAS using the deployment script:

```bash
# Deploy to internal network (10.0.0.81)
npm run deploy:pokedex:internal

# Deploy to external network (home.gregrjacobs.com)
npm run deploy:pokedex:external

# Deploy with custom ports
npm run deploy:pokedex -- --target internal --port 8080 --ssl-port 8443
```

## 📁 Project Structure

```
pokedex.online/
├── src/
│   ├── main.js                    # Application entry point
│   ├── App.vue                    # Root component with transitions
│   ├── style.css                  # Global styles
│   ├── router/
│   │   └── index.js              # Vue Router configuration (4 routes)
│   ├── views/
│   │   ├── Home.vue              # Landing page with tool cards
│   │   ├── ApiKeyManager.vue     # API key storage and management
│   │   ├── GamemasterManager.vue # Gamemaster fetch/process/download
│   │   └── ChallongeTest.vue     # API testing and validation
│   ├── components/
│   │   └── shared/
│   │       └── ProfessorPokeball.vue # Animated logo component
│   ├── services/
│   │   └── challonge.service.js  # Challonge API client (20+ methods)
│   ├── utilities/
│   │   ├── constants.js          # API config, types, CSV headers
│   │   ├── string-utils.js       # String utilities
│   │   ├── csv-utils.js          # CSV parsing and validation
│   │   ├── participant-utils.js  # Participant management
│   │   ├── gamemaster-utils.js   # Gamemaster processing
│   │   └── models/               # Data models (Tournament, Participant, Pokemon)
│   └── composables/
│       └── useChallongeApiKey.js # API key storage composable
├── .env.example                  # Environment template (optional)
├── index.html                    # HTML entry point
├── vite.config.js                # Vite config with dev proxy
├── nginx.conf                    # Production nginx proxy config
├── package.json                  # Dependencies (Vue 3, Vue Router)
├── Dockerfile                    # Docker build (nginx:alpine)
├── docker-compose.yml            # Docker Compose config
├── PROJECT_PLAN.md               # Implementation roadmap
├── API_KEY_STORAGE.md            # API key storage documentation
└── README.md                     # This file
```

## 🎯 Available Tools

### API Key Manager (`/api-key-manager`)
- Store your Challonge API key locally in browser localStorage
- Works across all devices and browsers (mobile, tablet, desktop)
- Masked display for security (shows "xxxx•••••••xxxx")
- Update or clear your key anytime
- No need to edit .env files
- Secure browser-native storage

### Gamemaster Manager (`/gamemaster`)
- Fetch latest Pokemon GO gamemaster from PokeMiners
- Process and break up into separate files
- Download pokemon.json, moves.json, and allFormsCostumes.json
- View statistics about downloaded data

### Challonge API Test (`/challonge-test`)
- Test your Challonge API connection
- Enter API key (or load from stored key)
- List your tournaments
- View tournament details and participants
- Verify API configuration is working

### Printing Tool (Coming Soon)
- Import RK9 player CSV files
- Generate team sheets
- Create player badges
- Print tournament materials

### 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:

```bash
# ✅ Correct - Available in browser
VITE_CHALLONGE_API_KEY=abc123

# ❌ Wrong - Not accessible
CHALLONGE_API_KEY=abc123
```

Access in code:
```javascript
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](./PROJECT_PLAN.md) - Complete implementation roadmap
- [GAMEMASTER_IMPLEMENTATION.md](./GAMEMASTER_IMPLEMENTATION.md) - Gamemaster feature details
- [Vue 3 Docs](https://vuejs.org/)
- [Challonge API](https://api.challonge.com/v1)

## 🔒 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