# greatsage/pokemon-showdown architecture

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

- Interactive diagram: https://gitdiagram.com/greatsage/pokemon-showdown
- Repository: https://github.com/greatsage/pokemon-showdown

## Overview

Showdown is a Node.js Pokémon battle simulator and multiplayer server. Players connect to the server, join rooms, chat or challenge/search for an opponent, and make battle decisions; rooms coordinate battles and relay simulator updates. User identity and permissions, command handling, format/team validation, and generation-specific battle data support that workflow. The excerpts show the server dispatching to users and rooms, room creation and battle coordination, and tools loading battle data; some internal links and documented login/ladder integration are not fully shown, so those links are omitted or marked optional.

Main entry points: [`tools.js`](https://github.com/greatsage/pokemon-showdown/blob/master/tools.js) (Battle Data Tools), [`rooms.js`](https://github.com/greatsage/pokemon-showdown/blob/master/rooms.js) (Room Coordination), [`users.js`](https://github.com/greatsage/pokemon-showdown/blob/master/users.js) (User Sessions), [`app.js`](https://github.com/greatsage/pokemon-showdown/blob/master/app.js) (Socket Server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_server["Server and Rooms"]
  node_app["Socket Server<br/>[app.js]"]
  node_rooms["Room Coordination<br/>[rooms.js]"]
end

subgraph group_identity["Users and Commands"]
  node_users["User Sessions<br/>[users.js]"]
  node_commands["Chat Commands<br/>[chat-commands.js]"]
end

subgraph group_battle["Battle Runtime"]
  node_simulator["Battle Simulator<br/>[simulator.js]"]
end

subgraph group_rules["Formats and Data"]
  node_tools["Battle Data Tools<br/>[tools.js]"]
  node_formats["Battle Formats<br/>[formats.js]"]
  node_formatdata["Format Metadata<br/>[formats-data.js]"]
  node_pokedex["Pokédex<br/>[pokedex.js]"]
  node_moves["Moves<br/>[moves.js]"]
  node_abilities["Abilities<br/>[abilities.js]"]
  node_items["Items<br/>[items.js]"]
  node_learnsets["Learnsets<br/>[learnsets.js]"]
  node_scripts["Battle Scripts<br/>[scripts.js]"]
  node_statuses["Status Effects<br/>[statuses.js]"]
  node_typechart["Type Chart<br/>[typechart.js]"]
  node_gen4moves["Gen 4 Overrides<br/>[moves.js]"]
  node_gen4pokedex["Gen 4 Pokémon<br/>[pokedex.js]"]
  node_gen4abilities["Gen 4 Abilities<br/>[abilities.js]"]
  node_gen4items["Gen 4 Items<br/>[items.js]"]
  node_gen4scripts["Gen 4 Scripts<br/>[scripts.js]"]
  node_gen5items["Gen 5 Items<br/>[items.js]"]
end

node_player(("Player"))
node_login["Login and Ladder Service"]

node_player -->|"connects"| node_app
node_app -->|"resolves sessions"| node_users
node_app -->|"routes room events"| node_rooms
node_app -->|"dispatches commands"| node_commands
node_users -->|"joins and leaves"| node_rooms
node_users -.->|"parses chat"| node_commands
node_commands -->|"looks up users"| node_users
node_rooms -->|"starts battles"| node_simulator
node_rooms -->|"finds players"| node_users
node_simulator -.->|"uses battle data"| node_tools
node_tools -->|"loads data"| node_formats
node_tools -->|"loads data"| node_formatdata
node_tools -->|"loads data"| node_pokedex
node_tools -->|"loads data"| node_moves
node_tools -->|"loads data"| node_abilities
node_tools -->|"loads data"| node_items
node_tools -->|"loads data"| node_learnsets
node_tools -->|"loads data"| node_scripts
node_tools -->|"loads data"| node_statuses
node_tools -->|"loads data"| node_typechart
node_tools -.->|"loads mods"| node_gen4moves
node_tools -.->|"loads mods"| node_gen4pokedex
node_tools -.->|"loads mods"| node_gen4abilities
node_tools -.->|"loads mods"| node_gen4items
node_tools -.->|"loads mods"| node_gen4scripts
node_tools -.->|"loads mods"| node_gen5items
node_rooms -.->|"updates ladder"| node_login

click node_app "https://github.com/greatsage/pokemon-showdown/blob/master/app.js"
click node_rooms "https://github.com/greatsage/pokemon-showdown/blob/master/rooms.js"
click node_users "https://github.com/greatsage/pokemon-showdown/blob/master/users.js"
click node_commands "https://github.com/greatsage/pokemon-showdown/blob/master/chat-commands.js"
click node_simulator "https://github.com/greatsage/pokemon-showdown/blob/master/simulator.js"
click node_tools "https://github.com/greatsage/pokemon-showdown/blob/master/tools.js"
click node_formats "https://github.com/greatsage/pokemon-showdown/blob/master/data/formats.js"
click node_formatdata "https://github.com/greatsage/pokemon-showdown/blob/master/mods/gen5-bw/formats-data.js"
click node_pokedex "https://github.com/greatsage/pokemon-showdown/blob/master/data/pokedex.js"
click node_moves "https://github.com/greatsage/pokemon-showdown/blob/master/data/moves.js"
click node_abilities "https://github.com/greatsage/pokemon-showdown/blob/master/data/abilities.js"
click node_items "https://github.com/greatsage/pokemon-showdown/blob/master/data/items.js"
click node_learnsets "https://github.com/greatsage/pokemon-showdown/blob/master/data/learnsets.js"
click node_scripts "https://github.com/greatsage/pokemon-showdown/blob/master/data/scripts.js"
click node_statuses "https://github.com/greatsage/pokemon-showdown/blob/master/data/statuses.js"
click node_typechart "https://github.com/greatsage/pokemon-showdown/blob/master/data/typechart.js"
click node_gen4moves "https://github.com/greatsage/pokemon-showdown/blob/master/mods/gen4/moves.js"
click node_gen4pokedex "https://github.com/greatsage/pokemon-showdown/blob/master/mods/gen4/pokedex.js"
click node_gen4abilities "https://github.com/greatsage/pokemon-showdown/blob/master/mods/gen4/abilities.js"
click node_gen4items "https://github.com/greatsage/pokemon-showdown/blob/master/mods/gen4/items.js"
click node_gen4scripts "https://github.com/greatsage/pokemon-showdown/blob/master/mods/gen4/scripts.js"
click node_gen5items "https://github.com/greatsage/pokemon-showdown/blob/master/mods/gen5-bw/items.js"

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_app,node_rooms toneBlue
class node_users,node_commands toneAmber
class node_simulator toneMint
class node_tools,node_formats,node_formatdata,node_pokedex,node_moves,node_abilities,node_items,node_learnsets,node_scripts,node_statuses,node_typechart,node_gen4moves,node_gen4pokedex,node_gen4abilities,node_gen4items,node_gen4scripts,node_gen5items toneRose
class node_player,node_login toneIndigo
```

## Components

### Server and Rooms

- [Socket Server](https://github.com/greatsage/pokemon-showdown/blob/master/app.js): `app.js`
- [Room Coordination](https://github.com/greatsage/pokemon-showdown/blob/master/rooms.js): `rooms.js`

### Users and Commands

- [User Sessions](https://github.com/greatsage/pokemon-showdown/blob/master/users.js): `users.js`
- [Chat Commands](https://github.com/greatsage/pokemon-showdown/blob/master/chat-commands.js): `chat-commands.js`

### Battle Runtime

- [Battle Simulator](https://github.com/greatsage/pokemon-showdown/blob/master/simulator.js): `simulator.js`

### Formats and Data

- [Battle Data Tools](https://github.com/greatsage/pokemon-showdown/blob/master/tools.js): `tools.js`
- [Battle Formats](https://github.com/greatsage/pokemon-showdown/blob/master/data/formats.js): `data/formats.js`
- [Format Metadata](https://github.com/greatsage/pokemon-showdown/blob/master/mods/gen5-bw/formats-data.js): `mods/gen5-bw/formats-data.js`
- [Pokédex](https://github.com/greatsage/pokemon-showdown/blob/master/data/pokedex.js): `data/pokedex.js`
- [Moves](https://github.com/greatsage/pokemon-showdown/blob/master/data/moves.js): `data/moves.js`
- [Abilities](https://github.com/greatsage/pokemon-showdown/blob/master/data/abilities.js): `data/abilities.js`
- [Items](https://github.com/greatsage/pokemon-showdown/blob/master/data/items.js): `data/items.js`
- [Learnsets](https://github.com/greatsage/pokemon-showdown/blob/master/data/learnsets.js): `data/learnsets.js`
- [Battle Scripts](https://github.com/greatsage/pokemon-showdown/blob/master/data/scripts.js): `data/scripts.js`
- [Status Effects](https://github.com/greatsage/pokemon-showdown/blob/master/data/statuses.js): `data/statuses.js`
- [Type Chart](https://github.com/greatsage/pokemon-showdown/blob/master/data/typechart.js): `data/typechart.js`
- [Gen 4 Overrides](https://github.com/greatsage/pokemon-showdown/blob/master/mods/gen4/moves.js): `mods/gen4/moves.js`
- [Gen 4 Pokémon](https://github.com/greatsage/pokemon-showdown/blob/master/mods/gen4/pokedex.js): `mods/gen4/pokedex.js`
- [Gen 4 Abilities](https://github.com/greatsage/pokemon-showdown/blob/master/mods/gen4/abilities.js): `mods/gen4/abilities.js`
- [Gen 4 Items](https://github.com/greatsage/pokemon-showdown/blob/master/mods/gen4/items.js): `mods/gen4/items.js`
- [Gen 4 Scripts](https://github.com/greatsage/pokemon-showdown/blob/master/mods/gen4/scripts.js): `mods/gen4/scripts.js`
- [Gen 5 Items](https://github.com/greatsage/pokemon-showdown/blob/master/mods/gen5-bw/items.js): `mods/gen5-bw/items.js`

### Other components

- **Player**
- **Login and Ladder Service**

## Connections

- Player → Socket Server: connects (evidence: `README.md`)
- Socket Server → User Sessions: resolves sessions (evidence: `app.js`)
- Socket Server → Room Coordination: routes room events (evidence: `app.js`)
- Socket Server → Chat Commands: dispatches commands (evidence: `app.js`)
- User Sessions → Room Coordination: joins and leaves (evidence: `users.js`)
- User Sessions → Chat Commands: parses chat
- Chat Commands → User Sessions: looks up users (evidence: `chat-commands.js`)
- Room Coordination → Battle Simulator: starts battles (evidence: `rooms.js`)
- Room Coordination → User Sessions: finds players (evidence: `rooms.js`)
- Battle Simulator → Battle Data Tools: uses battle data
- Battle Data Tools → Battle Formats: loads data (evidence: `tools.js`)
- Battle Data Tools → Format Metadata: loads data (evidence: `tools.js`)
- Battle Data Tools → Pokédex: loads data (evidence: `tools.js`)
- Battle Data Tools → Moves: loads data (evidence: `tools.js`)
- Battle Data Tools → Abilities: loads data (evidence: `tools.js`)
- Battle Data Tools → Items: loads data (evidence: `tools.js`)
- Battle Data Tools → Learnsets: loads data (evidence: `tools.js`)
- Battle Data Tools → Battle Scripts: loads data (evidence: `tools.js`)
- Battle Data Tools → Status Effects: loads data (evidence: `tools.js`)
- Battle Data Tools → Type Chart: loads data (evidence: `tools.js`)
- Battle Data Tools → Gen 4 Overrides: loads mods
- Battle Data Tools → Gen 4 Pokémon: loads mods
- Battle Data Tools → Gen 4 Abilities: loads mods
- Battle Data Tools → Gen 4 Items: loads mods
- Battle Data Tools → Gen 4 Scripts: loads mods
- Battle Data Tools → Gen 5 Items: loads mods
- Room Coordination → Login and Ladder Service: updates ladder (evidence: `README.md`)
