# bismarckssr/playscopa-stress-tester architecture

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

- Interactive diagram: https://gitdiagram.com/bismarckssr/playscopa-stress-tester
- Repository: https://github.com/bismarckssr/playscopa-stress-tester

## Overview

##### Project Type and Purpose
- This is an open-source command-line stress-testing tool that simulates many concurrent WebSocket clients against a remote Playscopa server.
- It is not a full-stack web app; it is primarily a concurrency-driven client simulator.

##### File Structure
- Top-level:
- `.env.example` / `.env` → environment configuration
- `pyproject.toml`, `requirements.txt` → Python packaging & dependencies
- `src/` → application code
- `tests/` → unit tests
- `.github/workflows/ci.yml` → CI pipeline
- `src/` breakdown:
- `config.py` → loads `.env` into config objects
- `client.py` → `StressClient` class (listener loop, sender tasks, asyncio.Events)
- `main.py` → entry point; reads config, spins up clients under `asyncio.TaskGroup`

##### Key Architecture Insights from README
- Async I/O pattern: each virtual client runs two coroutines (listener + sender) synchronized via events.
- External dependency: the remote WebSocket server (Playscopa).
- Configurable parameters: server URL, number of clients, test duration.

##### Main Components
a. Config Loader
- Loads `.env` → exposes `WEBSOCKET_URL`, `STRESSER_SESSIONS`, etc.
b. Orchestrator (main application)
- Reads config → creates an `asyncio.TaskGroup`
- Launches N instances of `StressClient`
c. StressClient Instances (multiple)
- Listener Loop coroutine
- Sender coroutine
- Two `asyncio.Event` objects for synchronization (`cards_populated`, `clear_to_send`)
d. External WebSocket Server
- Accepts client connections
- Sends messages (`welcome`, `ping`, `startingCards`, `turn`, etc.)
- Receives responses (options request, pong, moves)
e. CI Pipeline & Tests (optional)
- Runs unit tests against `src/` modules
- Ensures code quality on push (ci.yml)

##### Relationships and Data Flows
- Config Loader → Orchestrator (injects settings)
- Orchestrator → spawns StressClient instances
- Listener Loop ← server messages
- Sender → server actions
- Within each StressClient:
- Listener Loop sets events on receiving `startingCards` / `turn`
- Sender waits on events, then sends move

##### Architectural Patterns & Design Principles
- Asynchronous concurrency via `asyncio.TaskGroup`
- Separation of concerns:
- `config.py` for environment loading
- `client.py` for protocol logic
- `main.py` for orchestration
- Event-driven synchronization (asyncio.Events)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Configuration Layer
    Config["Config Loader"]:::config
    click Config "https://github.com/bismarckssr/playscopa-stress-tester/blob/main/src/config.py"

    %% Orchestration Layer
    Main["Orchestrator (main.py)"]:::orchestration
    click Main "https://github.com/bismarckssr/playscopa-stress-tester/blob/main/src/main.py"

    %% Client Logic Layer
    subgraph "StressClient Instances" 
        direction TB
        Client["StressClient"]:::client
        click Client "https://github.com/bismarckssr/playscopa-stress-tester/blob/main/src/client.py"
        Listener["Listener Loop\n(coroutine)"]:::client
        Sender["Sender Coroutine"]:::client
        Events["asyncio.Events\n(cards_populated, clear_to_send)"]:::client

        Listener -->|"sets events"| Events
        Events -->|"signals Sender"| Sender
    end

    %% External System
    WebSocket["External WebSocket Server"]:::external

    %% CI and Tests
    CI["CI Pipeline"]:::ci
    click CI "https://github.com/bismarckssr/playscopa-stress-tester/blob/main/.github/workflows/ci.yml"
    Tests["Unit Tests"]:::tests
    click Tests "https://github.com/bismarckssr/playscopa-stress-tester/tree/main/tests/"

    %% Relationships
    Config -->|"provides settings"| Main
    Main -->|"spawns N instances of"| Client
    Client <-->|"WebSocket messages/events"| WebSocket

    CI -->|"runs tests on push"| Tests
    Tests -->|"validate modules"| Config
    Tests -->|"validate modules"| Main
    Tests -->|"validate modules"| Client

    %% Styling
    classDef config fill:#e5ffe5,stroke:#2ca02c,color:#000
    classDef orchestration fill:#e5f2ff,stroke:#1f77b4,color:#000
    classDef client fill:#fff5e6,stroke:#ff7f0e,color:#000
    classDef external fill:#e6e6ff,stroke:#9467bd,color:#000
    classDef ci fill:#ffe6f0,stroke:#8c564b,color:#000
    classDef tests fill:#f0f0f0,stroke:#7f7f7f,color:#000
```
