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

Pokedex Online

A modern Vue 3 web application for Pokemon Professors to manage tournaments, process gamemaster data, and handle tournament printing materials.

📚 Documentation

All documentation has been reorganized into /docs/projects/Pokedex.Online/:

• Refactoring Plan - Comprehensive refactoring roadmap (11-week plan)
• Setup Guides - /docs/projects/Pokedex.Online/setup/
  • Gamemaster Setup
• API Reference - /docs/projects/Pokedex.Online/api-reference/
  • OAuth Setup
  • Gamemaster API
• Architecture - /docs/projects/Pokedex.Online/architecture/ (coming soon)
• Roadmap - /docs/projects/Pokedex.Online/roadmap/
  • Future Features
• Archive - /docs/projects/Pokedex.Online/archive/ (historical documents)

Features

• Gamemaster Manager - Fetch Pokemon GO gamemaster data from PokeMiners and process it into filtered/unfiltered datasets
• Gamemaster Explorer - Search, filter, and explore JSON files with virtual scrolling (1600+ lines)
• Gamemaster API - Access processed gamemaster data from any app on the site via REST API
• Challonge Integration - Manage tournaments with OAuth authentication (API v1 & v2.1)
• API Key Manager - Securely store API keys in browser storage

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

   cp .env.example .env
   

2. Configure your API keys in .env:

   # 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

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

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

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

# 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

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

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

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