# pkmn/ps architecture

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

- Interactive diagram: https://gitdiagram.com/pkmn/ps
- Repository: https://github.com/pkmn/ps

## Overview

##### Main Components

- Simulator Component (@pkmn/sim):
– This package is an extraction of the Pokémon Showdown simulator portion and forms the core engine for battles.

- Data and Dex Components (@pkmn/dex and @pkmn/data):
– The “dex” package unifies data from both server and client codebases, while “data” is a higher-level wrapper API.
– Show these components as being tightly coupled; the “Data API” draws information from the “Dex” (data unification) source.

- Mods (@pkmn/mods):
– Provides support for non-standard modifications to both sim and dex.
– Represent this as an “Extension/Modification” layer that plugs into the simulator and data components.

- Sets (@pkmn/sets):
– This handles importing/exporting Pokémon Showdown’s team/set specifications.

- Types (@pkmn/types):
– Provides shared TypeScript definitions, which are used throughout the system.

- Protocol (@pkmn/protocol):
– Contains parsing logic for the Pokémon Showdown protocols. It is used by other components (for example, the client component).

- Client (@pkmn/client):
– A fork of the Pokémon Showdown client battle engine that builds on top of the protocol.

- View (@pkmn/view):
– Its purpose is to build UIs for the client side.

- Img (@pkmn/img):

- Login (@pkmn/login):
– Manages authentication logic.

- Randoms (@pkmn/randoms):
– Implements random team generation for Random Battle formats.

- Streams (@pkmn/streams):
– Extracts the streams library from Pokémon Showdown.

- Integration and Other Supporting Folders:
– “integration”, “login”, and other directories contain testing frameworks, integration tests and additional scripts for building or simulating parts of the system.

##### Relationships & Data Flow

- Most packages depend on each other in a layered fashion. For example, the Client component uses the Protocol package to communicate, while the Simulator (sim) may pull in data from Dex and be modified by Mods.
- The Data component is a central API that wraps around and integrates both the simulator and dex functionalities.
- The Types package is a foundational library that all other components reference.
- UI-related components (Client and View) depend on Protocol, which in turn interacts with the underlying simulation logic from “sim”.
- Testing and integration directories that validate individual components and their interactions.

##### Architectural Patterns and Design Principles

- Separation of Concerns: Each package has a clearly defined role (e.g., simulation, data processing, rendering, authentication).
- Layered Architecture: Emphasize how the lower-level simulation and data models are abstracted by higher-level components (like the client and view).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Low-Level Libraries
    subgraph "Low-Level Libraries"
        types["@pkmn/types<br/>Shared TS definitions"]:::library
        streams["@pkmn/streams<br/>Stream library"]:::library
    end

    %% Core Simulation Components
    subgraph "Core Simulation"
        sim["Battle Engine (@pkmn/sim)"]:::core
        dex["Dex (@pkmn/dex)<br/>Data unification"]:::core
        data["Data (@pkmn/data)<br/>Wrapper API"]:::core
        mods["Mods (@pkmn/mods)<br/>Extensions/Modifications"]:::core
        sets["Sets (@pkmn/sets)<br/>Team/Set Specifications"]:::core
    end

    %% Client Interaction Components
    subgraph "Client Interaction"
        protocol["Protocol (@pkmn/protocol)<br/>Parsing logic"]:::ui
        client["Client (@pkmn/client)<br/>Battle interface fork"]:::ui
        view["View (@pkmn/view)<br/>UI Rendering"]:::ui
        img["Img (@pkmn/img)<br/>Sprite/Icon resources"]:::ui
        login["Login (@pkmn/login)<br/>Authentication"]:::ui
        randoms["Randoms (@pkmn/randoms)<br/>Random team generation"]:::ui
    end

    %% Integration and Testing
    subgraph "Integration/Testing"
        integration["Integration & Testing<br/>Frameworks and Scripts"]:::integration
    end

    %% Relationships
    client -->|"depends_on"| protocol
    protocol -->|"interfaces_with"| sim
    data -->|"aggregates"| dex
    data -->|"wraps"| sim
    mods -->|"modifies"| sim
    mods -->|"extends"| data
    sim -->|"imports_exports"| sets
    view -->|"uses"| protocol
    view -->|"renders"| img
    client -->|"authenticates_with"| login
    sim -->|"generates"| randoms

    %% Integration testing connections
    integration ---|"tests"| sim
    integration ---|"tests"| data
    integration ---|"tests"| dex
    integration ---|"tests"| client

    %% Foundational dependencies on Types and Streams
    sim ---|"uses"| types
    dex ---|"uses"| types
    data ---|"uses"| types
    mods ---|"uses"| types
    protocol ---|"uses"| types
    client ---|"uses"| types
    view ---|"uses"| types
    login ---|"uses"| types
    randoms ---|"uses"| types
    protocol ---|"utilizes"| streams

    %% Click Events
    click sim "https://github.com/pkmn/ps/tree/main/sim"
    click data "https://github.com/pkmn/ps/tree/main/data"
    click dex "https://github.com/pkmn/ps/tree/main/dex"
    click mods "https://github.com/pkmn/ps/tree/main/mods"
    click sets "https://github.com/pkmn/ps/tree/main/sets"
    click types "https://github.com/pkmn/ps/tree/main/types"
    click protocol "https://github.com/pkmn/ps/tree/main/protocol"
    click client "https://github.com/pkmn/ps/tree/main/client"
    click view "https://github.com/pkmn/ps/tree/main/view"
    click img "https://github.com/pkmn/ps/tree/main/img"
    click login "https://github.com/pkmn/ps/tree/main/login"
    click randoms "https://github.com/pkmn/ps/tree/main/randoms"
    click streams "https://github.com/pkmn/ps/tree/main/streams"
    click integration "https://github.com/pkmn/ps/tree/main/integration"

    %% Style Definitions
    classDef core fill:#ffcccc,stroke:#ff0000,stroke-width:2px;
    classDef ui fill:#ccffcc,stroke:#008000,stroke-width:2px;
    classDef library fill:#ccccff,stroke:#0000ff,stroke-width:2px;
    classDef integration fill:#ffffcc,stroke:#999900,stroke-dasharray: 5 5,stroke-width:2px;
```
