# ckeen302/pokeiq architecture

> Architecture diagram of the GitHub repository ckeen302/pokeiq, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ckeen302/pokeiq
- Repository: https://github.com/ckeen302/pokeiq
- Video tour (about a minute): https://gitdiagram.com/ckeen302/pokeiq/video

## Overview

PokéIQ serves live-generated Pokémon quizzes, then records results for personal progression and competition. The main path runs from a player choosing a quiz through the shared quiz controller, question API, category engine and PokéAPI-backed data, then returns sealed questions for server-verified answers. Daily Gauntlet uses a separate seeded challenge endpoint; accounts, Trainer Cards, badges and leaderboards form progression branches. Some UI and storage wiring is inferred from the README and file tree where source excerpts were not provided.

Main entry points: [`src/engines/index.ts`](https://github.com/ckeen302/pokeiq/blob/main/src/engines/index.ts) (Engine registry), [`src/components/quiz/QuizController.tsx`](https://github.com/ckeen302/pokeiq/blob/main/src/components/quiz/QuizController.tsx) (Quiz controller), [`src/components/quiz/QuizResults.tsx`](https://github.com/ckeen302/pokeiq/blob/main/src/components/quiz/QuizResults.tsx) (Quiz results), [`src/lib/pokeapi.ts`](https://github.com/ckeen302/pokeiq/blob/main/src/lib/pokeapi.ts) (PokéAPI client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Player experience"]
  node_quiz_pages["Quiz pages<br/>[page.tsx]"]
  node_daily_page["Daily page<br/>[page.tsx]"]
  node_quiz_controller["Quiz controller<br/>[QuizController.tsx]"]
  node_quiz_results["Quiz results<br/>[QuizResults.tsx]"]
  node_leaderboard_page["Leaderboard page<br/>[page.tsx]"]
  node_trainer_page["Trainer page<br/>[page.tsx]"]
  node_auth_form["Account form<br/>[AuthForm.tsx]"]
end

subgraph group_quiz["Quiz runtime"]
  node_question_api["Question API<br/>[route.ts]"]
  node_daily_api["Daily API<br/>[route.ts]"]
  node_engine_registry["Engine registry<br/>[index.ts]"]
  node_whos_engine["Who's That engine<br/>[engine.ts]"]
  node_type_engine["Type Detective engine<br/>[engine.ts]"]
  node_move_engine["Move Master engine<br/>[engine.ts]"]
  node_stat_engine["Stat Showdown engine<br/>[engine.ts]"]
  node_engine_validation["Question validation<br/>[validate.ts]"]
  node_answer_tokens["Answer tokens<br/>[answer-token.ts]"]
  node_daily_seed["Daily challenge<br/>[daily.ts]"]
end

subgraph group_progression["Progression"]
  node_leaderboard_api["Leaderboard API<br/>[route.ts]"]
  node_leaderboard_store[("Leaderboard store")]
  node_stats_api["Stats API<br/>[route.ts]"]
  node_auth_api["Account APIs"]
  node_auth_store[("Account store<br/>[auth-store.ts]")]
  node_achievements["Gym badges<br/>[achievements.ts]"]
end

subgraph group_services["Data services"]
  node_pokeapi_client["PokéAPI client<br/>[pokeapi.ts]"]
end

node_player(("Player"))
node_pokemon_api["PokéAPI"]
node_supabase[("Supabase")]
node_browser[("Browser storage")]

node_player -->|"chooses quiz"| node_quiz_pages
node_player -->|"starts daily"| node_daily_page
node_quiz_pages -->|"renders"| node_quiz_controller
node_daily_page -->|"renders"| node_quiz_controller
node_quiz_controller -->|"requests questions"| node_question_api
node_question_api -->|"generates batch"| node_engine_registry
node_engine_registry -->|"dispatches"| node_whos_engine
node_engine_registry -->|"dispatches"| node_type_engine
node_engine_registry -->|"dispatches"| node_move_engine
node_engine_registry -->|"dispatches"| node_stat_engine
node_engine_registry -->|"validates output"| node_engine_validation
node_whos_engine -->|"fetches Pokémon"| node_pokeapi_client
node_type_engine -->|"fetches type data"| node_pokeapi_client
node_move_engine -->|"fetches move data"| node_pokeapi_client
node_stat_engine -->|"fetches stats"| node_pokeapi_client
node_pokeapi_client -->|"requests resources"| node_pokemon_api
node_question_api -->|"seals answers"| node_answer_tokens
node_quiz_controller -->|"submits answer"| node_question_api
node_daily_page -->|"requests challenge"| node_daily_api
node_daily_api -->|"gets seeded run"| node_daily_seed
node_daily_api -->|"seals answers"| node_answer_tokens
node_quiz_controller -->|"submits answer"| node_daily_api
node_quiz_controller -->|"shows results"| node_quiz_results
node_quiz_results -->|"records run"| node_stats_api
node_quiz_results -->|"submits score"| node_leaderboard_api
node_quiz_results -->|"checks badges"| node_achievements
node_quiz_results -.->|"stores guest stats"| node_browser
node_player -->|"views rankings"| node_leaderboard_page
node_leaderboard_page -->|"loads scores"| node_leaderboard_api
node_leaderboard_api -->|"reads and writes"| node_leaderboard_store
node_leaderboard_store -.->|"persists scores"| node_supabase
node_player -->|"signs in"| node_auth_form
node_auth_form -->|"sends credentials"| node_auth_api
node_auth_api -->|"manages accounts"| node_auth_store
node_auth_store -.->|"persists accounts"| node_supabase
node_auth_store -.->|"uses local fallback"| node_browser
node_player -->|"views profile"| node_trainer_page
node_trainer_page -->|"loads progress"| node_stats_api
node_stats_api -->|"records and ranks"| node_auth_store

click node_quiz_pages "https://github.com/ckeen302/pokeiq/blob/main/src/app/quiz/%5Bcategory%5D/page.tsx"
click node_daily_page "https://github.com/ckeen302/pokeiq/blob/main/src/app/daily/page.tsx"
click node_quiz_controller "https://github.com/ckeen302/pokeiq/blob/main/src/components/quiz/QuizController.tsx"
click node_quiz_results "https://github.com/ckeen302/pokeiq/blob/main/src/components/quiz/QuizResults.tsx"
click node_question_api "https://github.com/ckeen302/pokeiq/blob/main/src/app/api/questions/%5Bcategory%5D/route.ts"
click node_daily_api "https://github.com/ckeen302/pokeiq/blob/main/src/app/api/daily/route.ts"
click node_engine_registry "https://github.com/ckeen302/pokeiq/blob/main/src/engines/index.ts"
click node_whos_engine "https://github.com/ckeen302/pokeiq/blob/main/src/engines/whos-that/engine.ts"
click node_type_engine "https://github.com/ckeen302/pokeiq/blob/main/src/engines/type-detective/engine.ts"
click node_move_engine "https://github.com/ckeen302/pokeiq/blob/main/src/engines/move-master/engine.ts"
click node_stat_engine "https://github.com/ckeen302/pokeiq/blob/main/src/engines/stat-showdown/engine.ts"
click node_engine_validation "https://github.com/ckeen302/pokeiq/blob/main/src/engines/validate.ts"
click node_answer_tokens "https://github.com/ckeen302/pokeiq/blob/main/src/lib/answer-token.ts"
click node_daily_seed "https://github.com/ckeen302/pokeiq/blob/main/src/lib/daily.ts"
click node_pokeapi_client "https://github.com/ckeen302/pokeiq/blob/main/src/lib/pokeapi.ts"
click node_leaderboard_page "https://github.com/ckeen302/pokeiq/blob/main/src/app/leaderboard/page.tsx"
click node_leaderboard_api "https://github.com/ckeen302/pokeiq/blob/main/src/app/api/leaderboard/route.ts"
click node_leaderboard_store "https://github.com/ckeen302/pokeiq/blob/main/src/lib/leaderboard-store.ts"
click node_trainer_page "https://github.com/ckeen302/pokeiq/blob/main/src/app/trainer/page.tsx"
click node_stats_api "https://github.com/ckeen302/pokeiq/blob/main/src/app/api/stats/route.ts"
click node_auth_api "https://github.com/ckeen302/pokeiq/tree/main/src/app/api/auth"
click node_auth_store "https://github.com/ckeen302/pokeiq/blob/main/src/lib/auth-store.ts"
click node_auth_form "https://github.com/ckeen302/pokeiq/blob/main/src/components/AuthForm.tsx"
click node_achievements "https://github.com/ckeen302/pokeiq/blob/main/src/lib/achievements.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_quiz_pages,node_daily_page,node_quiz_controller,node_quiz_results,node_leaderboard_page,node_trainer_page,node_auth_form toneBlue
class node_question_api,node_daily_api,node_engine_registry,node_whos_engine,node_type_engine,node_move_engine,node_stat_engine,node_engine_validation,node_answer_tokens,node_daily_seed,node_supabase,node_browser toneAmber
class node_leaderboard_api,node_leaderboard_store,node_stats_api,node_auth_api,node_auth_store,node_achievements,node_pokemon_api toneMint
class node_pokeapi_client toneRose
class node_player toneIndigo
```

## Components

### Player experience

- [Quiz pages](https://github.com/ckeen302/pokeiq/blob/main/src/app/quiz/%5Bcategory%5D/page.tsx): `src/app/quiz/[category]/page.tsx`
- [Daily page](https://github.com/ckeen302/pokeiq/blob/main/src/app/daily/page.tsx): `src/app/daily/page.tsx`
- [Quiz controller](https://github.com/ckeen302/pokeiq/blob/main/src/components/quiz/QuizController.tsx): `src/components/quiz/QuizController.tsx`
- [Quiz results](https://github.com/ckeen302/pokeiq/blob/main/src/components/quiz/QuizResults.tsx): `src/components/quiz/QuizResults.tsx`
- [Leaderboard page](https://github.com/ckeen302/pokeiq/blob/main/src/app/leaderboard/page.tsx): `src/app/leaderboard/page.tsx`
- [Trainer page](https://github.com/ckeen302/pokeiq/blob/main/src/app/trainer/page.tsx): `src/app/trainer/page.tsx`
- [Account form](https://github.com/ckeen302/pokeiq/blob/main/src/components/AuthForm.tsx): `src/components/AuthForm.tsx`

### Quiz runtime

- [Question API](https://github.com/ckeen302/pokeiq/blob/main/src/app/api/questions/%5Bcategory%5D/route.ts): `src/app/api/questions/[category]/route.ts`
- [Daily API](https://github.com/ckeen302/pokeiq/blob/main/src/app/api/daily/route.ts): `src/app/api/daily/route.ts`
- [Engine registry](https://github.com/ckeen302/pokeiq/blob/main/src/engines/index.ts): `src/engines/index.ts`
- [Who's That engine](https://github.com/ckeen302/pokeiq/blob/main/src/engines/whos-that/engine.ts): `src/engines/whos-that/engine.ts`
- [Type Detective engine](https://github.com/ckeen302/pokeiq/blob/main/src/engines/type-detective/engine.ts): `src/engines/type-detective/engine.ts`
- [Move Master engine](https://github.com/ckeen302/pokeiq/blob/main/src/engines/move-master/engine.ts): `src/engines/move-master/engine.ts`
- [Stat Showdown engine](https://github.com/ckeen302/pokeiq/blob/main/src/engines/stat-showdown/engine.ts): `src/engines/stat-showdown/engine.ts`
- [Question validation](https://github.com/ckeen302/pokeiq/blob/main/src/engines/validate.ts): `src/engines/validate.ts`
- [Answer tokens](https://github.com/ckeen302/pokeiq/blob/main/src/lib/answer-token.ts): `src/lib/answer-token.ts`
- [Daily challenge](https://github.com/ckeen302/pokeiq/blob/main/src/lib/daily.ts): `src/lib/daily.ts`

### Progression

- [Leaderboard API](https://github.com/ckeen302/pokeiq/blob/main/src/app/api/leaderboard/route.ts): `src/app/api/leaderboard/route.ts`
- [Leaderboard store](https://github.com/ckeen302/pokeiq/blob/main/src/lib/leaderboard-store.ts): `src/lib/leaderboard-store.ts`
- [Stats API](https://github.com/ckeen302/pokeiq/blob/main/src/app/api/stats/route.ts): `src/app/api/stats/route.ts`
- [Account APIs](https://github.com/ckeen302/pokeiq/tree/main/src/app/api/auth): `src/app/api/auth`
- [Account store](https://github.com/ckeen302/pokeiq/blob/main/src/lib/auth-store.ts): `src/lib/auth-store.ts`
- [Gym badges](https://github.com/ckeen302/pokeiq/blob/main/src/lib/achievements.ts): `src/lib/achievements.ts`

### Data services

- [PokéAPI client](https://github.com/ckeen302/pokeiq/blob/main/src/lib/pokeapi.ts): `src/lib/pokeapi.ts`

### Other components

- **Player**
- **PokéAPI**
- **Supabase**
- **Browser storage**

## Connections

- Player → Quiz pages: chooses quiz
- Player → Daily page: starts daily
- Quiz pages → Quiz controller: renders
- Daily page → Quiz controller: renders
- Quiz controller → Question API: requests questions
- Question API → Engine registry: generates batch
- Engine registry → Who's That engine: dispatches
- Engine registry → Type Detective engine: dispatches
- Engine registry → Move Master engine: dispatches
- Engine registry → Stat Showdown engine: dispatches
- Engine registry → Question validation: validates output
- Who's That engine → PokéAPI client: fetches Pokémon
- Type Detective engine → PokéAPI client: fetches type data
- Move Master engine → PokéAPI client: fetches move data
- Stat Showdown engine → PokéAPI client: fetches stats
- PokéAPI client → PokéAPI: requests resources
- Question API → Answer tokens: seals answers
- Quiz controller → Question API: submits answer
- Daily page → Daily API: requests challenge
- Daily API → Daily challenge: gets seeded run
- Daily API → Answer tokens: seals answers
- Quiz controller → Daily API: submits answer
- Quiz controller → Quiz results: shows results
- Quiz results → Stats API: records run
- Quiz results → Leaderboard API: submits score
- Quiz results → Gym badges: checks badges
- Quiz results → Browser storage: stores guest stats
- Player → Leaderboard page: views rankings
- Leaderboard page → Leaderboard API: loads scores
- Leaderboard API → Leaderboard store: reads and writes
- Leaderboard store → Supabase: persists scores
- Player → Account form: signs in
- Account form → Account APIs: sends credentials
- Account APIs → Account store: manages accounts
- Account store → Supabase: persists accounts
- Account store → Browser storage: uses local fallback
- Player → Trainer page: views profile
- Trainer page → Stats API: loads progress
- Stats API → Account store: records and ranks