# PokeVerse - Pokémon Encyclopedia

This is a comprehensive Pokémon encyclopedia web application built with modern web technologies.

## Project Overview

A Next.js 15 application that provides detailed information about Pokémon species, types, abilities, and evolution chains using the PokéAPI as the data source. Features include daily Pokémon discovery, random exploration, type system analysis, and comprehensive search functionality.

## Technology Stack

- **Framework**: Next.js 15 with App Router pattern
- **Language**: TypeScript with strict type checking
- **Styling**: Tailwind CSS v4 with custom design system
- **Internationalization**: next-intl v4.4.0 for multilingual support (en, ja, pt-BR, roomaji)
- **Authentication**: Supabase Auth with Google OAuth integration
- **Database**: Supabase (PostgreSQL) with Row Level Security
- **Data Source**: PokéAPI (https://pokeapi.co/api/v2/)
- **Image Optimization**: Next.js Image component with CDN fallbacks
- **State Management**: React hooks and context (no external state library)
- **Build Tool**: Turbopack for development performance
- **PWA**: Progressive Web App with service worker and offline support
- **Package Manager**: pnpm (preferred) or npm
- **Deployment**: Cloudflare Pages with Edge Runtime

## Architecture

### Core Structure
- **App Router**: Uses Next.js 15 App Router with dynamic `[locale]` routing for internationalization
- **i18n System**: next-intl middleware for automatic locale detection and routing with translation message loading
- **API Layer**: Centralized API handling in `src/lib/api.ts` with comprehensive error handling
- **Type System**: Complete TypeScript definitions in `src/types/pokemon.ts`
- **Component Architecture**: Organized by domain (layout, pokemon, seo, ui)
- **Custom Hooks**: Data fetching and state management logic in `src/hooks/`

### Key Features
- **Multilingual Support**: Full internationalization with 4 languages (English, Japanese, Portuguese Brazilian, Romaji) using next-intl
- **Authentication & User Management**: Supabase integration with Google OAuth, user profiles, preferences, and favorites
- **Daily Pokémon**: Deterministic daily Pokémon generation per user with history tracking
- **Search System**: Direct name/ID search with input validation
- **Theme System**: Dark/light mode with system preference detection and persistence
- **SEO Optimization**: Metadata, structured data, robots.txt, sitemap covering 1328 Pokémon entries (1025 main-line + 303 form variants)
- **Error Handling**: Custom PokemonApiError class with user-friendly messages
- **Image Fallbacks**: Multi-tier fallback system for Pokémon images
- **PWA Support**: Service worker, offline pages, app manifest for installation
- **Guides System**: Comprehensive educational content covering strategies and tips
- **News System**: Structured news articles with featured/non-featured management and image optimization

## Directory Structure

```
src/
├── app/                    # Next.js App Router pages and layouts
│   ├── [locale]/          # Internationalized pages with dynamic locale routing
│   │   ├── daily/        # Daily Pokémon feature
│   │   ├── guides/       # Educational content and strategy guides
│   │   ├── news/         # News articles with structured content
│   │   ├── offline/      # PWA offline fallback page
│   │   ├── pokemon/      # Pokémon database and detail pages
│   │   ├── random/       # Random Pokémon discovery
│   │   └── types/        # Pokémon type system explorer
│   ├── api/              # API routes (vitals monitoring)
│   └── auth/             # Authentication routes
│       └── callback/     # OAuth callback handler (Edge Runtime)
├── components/            # Reusable UI components
│   ├── layout/           # Layout components (header, footer, navigation)
│   ├── pokemon/          # Pokémon-specific components
│   ├── seo/              # SEO and structured data components
│   └── ui/               # General UI components
├── hooks/                # Custom React hooks for data fetching
├── i18n/                 # Internationalization configuration
│   ├── routing.ts        # Locale routing configuration (en, ja, pt-BR, roomaji)
│   └── request.ts        # Request-scoped i18n setup
├── lib/                  # Utility functions and API client
│   ├── api.ts                    # PokéAPI client with error handling
│   ├── daily.ts                  # Daily Pokémon generation algorithms
│   ├── type-translations.ts      # Type name translation helpers
│   ├── ability-translations.ts   # Ability translation helpers
│   ├── csp.ts                    # Content Security Policy configuration
│   ├── nonce.ts                  # CSP nonce generation
│   ├── supabase/                 # Supabase client and utilities
│   │   ├── client.ts            # Client-side Supabase instance
│   │   ├── server.ts            # Server-side Supabase client
│   │   ├── middleware.ts        # Session refresh middleware
│   │   ├── auth.ts              # Authentication helpers
│   │   ├── profiles.ts          # User profile management
│   │   ├── preferences.ts       # User preferences management
│   │   ├── favorites.ts         # Favorite Pokémon management
│   │   └── daily.ts             # Daily Pokémon history tracking
│   └── __tests__/               # Unit test files (Jest)
├── types/                # TypeScript type definitions
├── constants/            # Application constants and configuration
└── styles/               # Global styles and design tokens
messages/                 # Translation files (en.json, ja.json, pt-BR.json, roomaji.json) with 438+ keys per locale
```

## Key Files

### Core Application
- `src/app/layout.tsx` - Root layout with theme provider and metadata
- `src/app/page.tsx` - Homepage with navigation cards
- `src/lib/api.ts` - PokéAPI client with error handling and caching
- `src/types/pokemon.ts` - Complete TypeScript definitions for Pokémon data

### Features
- `src/app/daily/page.tsx` - Daily Pokémon discovery feature
- `src/app/guides/` - Educational content and strategy guides
- `src/app/news/` - News articles with structured content and featured article management
- `src/app/offline/page.tsx` - PWA offline fallback page
- `src/app/pokemon/page.tsx` - Pokémon database listing
- `src/app/pokemon/[id]/page.tsx` - Individual Pokémon detail pages
- `src/app/random/page.tsx` - Random Pokémon exploration
- `src/app/types/page.tsx` - Pokémon type system explorer

### UI Components
- `src/components/pokemon/` - Pokémon-specific components (cards, lists, details)
- `src/components/ui/` - Reusable UI components (buttons, cards, loading states)
- `src/components/layout/` - Layout components (header, footer, navigation)

### Internationalization
- `src/i18n/routing.ts` - Locale routing configuration with supported locales (en, ja, pt-BR, roomaji)
- `src/i18n/request.ts` - Request-scoped i18n configuration and message loading
- `messages/en.json` - English translations (438+ keys)
- `messages/ja.json` - Japanese translations (438+ keys)
- `messages/pt-BR.json` - Portuguese Brazilian translations (438+ keys)
- `messages/roomaji.json` - Romaji translations (438+ keys)
- `src/lib/type-translations.ts` - Helper functions for translating Pokémon type names
- `src/lib/ability-translations.ts` - Helper functions for translating ability names and effects
- `src/middleware.ts` - Middleware integrating next-intl routing, Supabase auth, and CSP headers

### Utilities
- `src/lib/daily.ts` - Daily Pokémon generation logic
- `src/lib/utils.ts` - General utility functions
- `src/constants/` - Type colors, configuration, and constants
- `src/styles/design-tokens.ts` - Design system tokens and theme definitions

## Development

### Commands
- `pnpm dev` - Start development server with Turbopack (preferred)
- `npm run dev` - Start development server (alternative)
- `pnpm build` - Build production version
- `pnpm start` - Start production server
- `pnpm lint` - Run ESLint for code quality
- `pnpm test` - Run unit tests (Jest tests available in `src/lib/__tests__/`)
- `pnpm typecheck` - Run TypeScript type checking

### Code Patterns
- **Error Handling**: Custom error classes with specific error messages
- **Type Safety**: Strict TypeScript with comprehensive type definitions
- **Component Props**: Properly typed component interfaces
- **API Integration**: Centralized with fallback mechanisms
- **Responsive Design**: Mobile-first approach with Tailwind CSS
- **Performance**: Image optimization, lazy loading, and efficient data fetching

## Data Flow

1. **API Layer** (`src/lib/api.ts`) handles all external data fetching
2. **Custom Hooks** (`src/hooks/`) manage state and data fetching logic
3. **Components** consume data through hooks for separation of concerns
4. **Error Boundaries** handle API failures gracefully
5. **Loading States** provide user feedback during data fetching

## Special Features

### Internationalization (i18n) System
- **Supported Languages**: English (en), Japanese (ja), Portuguese Brazilian (pt-BR), and Romaji (roomaji)
- **Routing Strategy**: 'as-needed' prefix - English uses clean URLs (`/pokemon`), other locales include locale prefix (`/ja/pokemon`, `/pt-BR/pokemon`, `/roomaji/pokemon`)
- **Translation Coverage**: 438+ keys per locale covering UI, navigation, errors, and content
- **PokeAPI Integration**: Leverages PokeAPI's multilingual data for Pokémon names, types, abilities, and descriptions
- **Middleware**: Custom middleware chain handles locale routing, Supabase session management, and CSP headers with nonce generation
- **SEO Optimization**: Locale-specific metadata and Open Graph tags for multilingual SEO

### Authentication & User Management
- **Supabase Integration**: Complete backend with PostgreSQL database and Row Level Security
- **Google OAuth**: Sign-in with profile picture and display name support
- **User Data Structure**:
  - User profiles with avatar URLs, theme preferences, and metadata
  - User preferences (show shiny, default view, items per page)
  - Favorite Pokémon tracking
  - Daily Pokémon viewing history
  - Achievement tracking system
- **Security**: RLS policies ensure users can only access their own data
- **Edge Runtime**: Compatible with Cloudflare Pages deployment

### Daily Pokémon System
- Uses deterministic generation based on user ID and date
- Implemented in `src/lib/daily.ts`
- Creates consistent daily experiences across sessions with history tracking in Supabase

### Guides System
- Comprehensive educational content in `/guides/` directory
- Covers beginner guides, battle strategy, training, and discovery
- SEO-optimized articles with structured content

### PWA Implementation
- Service Worker (`public/sw.js`) for offline caching
- Web App Manifest (`src/app/manifest.ts`) for installation
- Offline page (`src/app/offline/page.tsx`) for graceful degradation
- Background sync and push notification infrastructure

### SEO Implementation
- Dynamic metadata generation for all pages (title ≤ 60 chars, description ≤ 160 chars, keywords ≤ 100 chars)
- Structured data (Schema.org) for rich search results
- Automatic sitemap generation covering 1328 Pokémon entries (1025 main-line + 303 form variants)
- Optimized robots.txt configuration
- Open Graph image generation for social media sharing

### Image Optimization
- Next.js Image component with multiple fallback sources
- CDN configuration for optimal loading
- Proper loading states and error handling

This codebase follows modern React/Next.js patterns with comprehensive TypeScript typing, error handling, and performance optimization throughout.