# wellplayedgg/react-sdk architecture

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

- Interactive diagram: https://gitdiagram.com/wellplayedgg/react-sdk
- Repository: https://github.com/wellplayedgg/react-sdk

## Overview

##### Main components
- SDK Core (Library)
– API Layer: Located in src/api with files like apollo.ts, several hooks (organization.hook.ts, paginated-query.hook.ts, players.hook.ts, teams.hook.ts, tournaments.hook.ts) and a WebSocket setup (ws.ts). This layer is responsible for interacting with external APIs (e.g., WellPlayed API) and handling GraphQL data.
– GraphQL Integration: Files such as schema.graphql, src/graphql.ts, and the GraphQL environment file (graphql-env.d.ts) indicate integration points for query/mutation operations.
– UI Components: Found in src/components (for example, rich-text-editor-content.tsx) and the provider component in src/wp.provider.tsx, which establishes the React context for SDK configuration.
– Type Definitions: The src/types directory provides important custom type declarations, including support for react-oidc.

- Demo Application
– A dedicated demo project (in the “demo” folder) that includes a simplified React setup. Within demo/src, there are features for “home” and “tournaments” (e.g., tournament-step.tsx, tournament-teams.tsx, tournament.tsx), a main entry file (main.tsx), and additional layout and utility files. This serves as both a usage example and testbed for the SDK components and hooks.

- Build & Configuration
– Both the SDK and demo use Vite for bundling (vite.config.ts in both root and demo directories), TypeScript configuration (tsconfig.json), and package management scripts (package.json, codegen.yml, etc.).
– Additional configuration files such as biome.json, graphql.config.yml, and CI/CD workflows under .github/workflows are present to manage deployments and automation tasks (e.g., deploying to npm).

##### Relationships and interactions
- At the top level, the SDK consumer (a developer’s React app) wraps their application with the WellPlayedProvider (from the SDK) to configure the connection with the WellPlayed API.
- The Provider uses the configuration to initialize the API layer (Apollo and WebSocket integrations) and exposes hooks (in src/api/hooks) to interact with the data.
- UI components and custom hooks (from the SDK Core) provide interfaces for rendering data and managing state, with some components (found in src/components) encapsulating complex UI logic like rich text editing.
- In the demo flow, the demo application imports and uses these components and hooks, showcasing various features (organized under demo/src/features) such as tournaments and home pages.

##### Architectural patterns
- Provider Pattern: The WellPlayedProvider in wp.provider.tsx establishes context and configuration, centralizing API setup and state management.
- Hook Pattern: Custom hooks in src/api/hooks simplify data fetching and integration with the WellPlayed API.
- Modular Design: Distinct separation between the SDK core and demo application illustrates a clean boundary between library code and usage examples.
- Integration with external services via GraphQL and Apollo, which is central to managing data flow between the UI and backend services.

##### Relevant technologies and frameworks
- React and TypeScript are used throughout.
- Vite is employed for bundling and development.
- GraphQL (with the Apollo client setup) is used for API interaction.
- The project utilizes CI/CD (via GitHub workflows) and adheres to code-generation practices (codegen.yml) common in modern SDKs.

##### Elements
- Clearly labeled nodes for each major component:
– SDK Core: API Layer, GraphQL Integration, UI Components, Custom Hooks, Type Definitions.
– Demo Application: Feature components (Home, Tournaments), Utilities, Entry point (main.tsx).
- Additional annotations to represent build/deployment configurations (CI/CD, Vite configurations).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Main Consumer Node
    Consumer["React App Consumer"]:::consumer

    %% SDK Core Subgraph
    subgraph "SDK Core"
        Provider["WellPlayedProvider"]:::sdk
        API_Layer["API Layer"]:::sdk
        GraphQL["GraphQL Integration"]:::sdk
        Hooks["Custom Hooks"]:::sdk
        UI_Components["UI Components"]:::sdk
        TypeDefinitions["Type Definitions"]:::sdk
    end

    %% Demo Application Subgraph
    subgraph "Demo Application"
        Demo_Entry["Demo App Entry (main.tsx)"]:::demo
        Home_Feature["Home Feature"]:::demo
        Tournaments["Tournaments Feature"]:::demo
    end

    %% Build & Configuration Subgraph
    subgraph "Build & Configuration"
        Build_Config["Project Build Config"]:::config
        CICD["CI/CD Workflows"]:::config
        Demo_Vite["Demo Vite Config"]:::config
    end

    %% Connections between Consumer and SDK Core
    Consumer -->|"wraps"| Provider
    Provider -->|"initializes"| API_Layer
    Provider -->|"configures"| GraphQL
    API_Layer -->|"provides"| Hooks
    GraphQL -->|"supports"| Hooks
    Hooks -->|"supplies data to"| UI_Components
    API_Layer -->|"utilizes"| TypeDefinitions

    %% Connections between Demo Application and SDK Core
    Demo_Entry -->|"integrates"| Provider
    Demo_Entry --> Home_Feature
    Demo_Entry --> Tournaments

    %% Connections from Build & Configuration to other parts
    Build_Config -->|"builds"| Provider
    Build_Config -->|"builds"| Demo_Entry
    CICD -->|"automates"| Build_Config
    Demo_Vite -->|"configures"| Demo_Entry

    %% Click Events
    click API_Layer "https://github.com/wellplayedgg/react-sdk/tree/master/src/api"
    click GraphQL "https://github.com/wellplayedgg/react-sdk/blob/master/src/graphql.ts"
    click Provider "https://github.com/wellplayedgg/react-sdk/blob/master/src/wp.provider.tsx"
    click UI_Components "https://github.com/wellplayedgg/react-sdk/tree/master/src/components"
    click TypeDefinitions "https://github.com/wellplayedgg/react-sdk/tree/master/src/types"
    click Demo_Entry "https://github.com/wellplayedgg/react-sdk/blob/master/demo/src/main.tsx"
    click Home_Feature "https://github.com/wellplayedgg/react-sdk/blob/master/demo/src/features/home/home.tsx"
    click Tournaments "https://github.com/wellplayedgg/react-sdk/tree/master/demo/src/features/tournaments"
    click Build_Config "https://github.com/wellplayedgg/react-sdk/blob/master/vite.config.ts"
    click CICD "https://github.com/wellplayedgg/react-sdk/blob/master/.github/workflows/deploy-to-npm.yaml"
    click Demo_Vite "https://github.com/wellplayedgg/react-sdk/blob/master/demo/vite.config.ts"

    %% Styling
    classDef consumer fill:#f9e79f,stroke:#d4ac0d,stroke-width:2px;
    classDef sdk fill:#cce5ff,stroke:#007bff,stroke-width:2px;
    classDef demo fill:#d4edda,stroke:#28a745,stroke-width:2px;
    classDef config fill:#fdebd0,stroke:#e67e22,stroke-width:2px;
```
