# jerempjerem/opensea-stream-py architecture

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

- Interactive diagram: https://gitdiagram.com/jerempjerem/opensea-stream-py
- Repository: https://github.com/jerempjerem/opensea-stream-py

## Overview

##### Project Type and Purpose
- This is a Python SDK (client library) named `opensea-stream` that connects to the OpenSea Stream API over WebSockets.
- Its job is to let user applications subscribe to NFT collection events (listed, sold, transferred, metadata updates, bids, offers, cancellations) and receive updates via callback functions or webhooks.

##### File Structure
- Top‐level files:
– `setup.py` & `requirements.txt` (packaging + dependencies)
– `README.md`, `LICENSE`, `.gitignore`
- Main module folder: `opensea-stream/`
– `opensea_stream.py` (contains `OpenseaStreamClient`, event types, connection logic, subscription methods)
– `utils.py` (helper code for message formatting, backoff, validation)
- No separate frontend or database—this is purely a library connecting to an external service.

##### Key Architecture Insights from README
- Uses websockets to connect to `wss://stream.openseabeta.com/socket` (mainnet) or testnet endpoint.
- Exposes methods like `onItemListed(…)`, `onEvents(…)`, `startListening()`.
- Internally manages authentication via API key, channel subscription, message parsing, and callback dispatch.
- Optionally integrates with a Discord webhook (via `discord_webhook` library).

##### Main Components
1. **User Application**
– Importing and instantiating `OpenseaStreamClient`.
– Registering callbacks or webhook handlers.
2. **SDK Library**
– Module: `opensea_stream.py`
- Connection Manager (handles WebSocket lifecycle)
- Subscription Manager (tracks event types & collection slugs)
- Event Dispatcher (observer/publish-subscribe pattern)
– Module: `utils.py`
- Message serialization/deserialization
- Retry/backoff logic
- Validation of payloads
3. **External OpenSea Stream Service**
– WebSocket endpoint (Mainnet or Testnet)
– Event feed server pushing JSON payloads over channels
4. **Optional External Service**
– Discord (Webhook) endpoint
– Any other third-party callback destinations

##### Relationships & Data Flows
- From **User App** → calls SDK subscription methods → updates Subscription Manager.
- **OpenseaStreamClient** → connects over WebSocket → authenticates with API key → subscribes to channels.
- External **Stream Service** → pushes events → SDK Connection Manager receives messages → passes to Event Dispatcher.
- **Event Dispatcher** → looks up matching user callback(s) → invokes callback function or sends to webhook via `discord_webhook`.
- Callbacks run in user’s process—handle payload however they choose (database writes, UI updates, logs, etc.).

##### Architectural Patterns & Design Principles
- Observer / Publish-Subscribe pattern for event callbacks
- Separation of concerns: connection handling, subscription management, message parsing in distinct modules
- Extensibility: new event types and networks (mainnet/testnet) can be added via enums and helper functions
- Resilience: automatic reconnect/backoff logic in `utils.py`

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Application
    subgraph "User Application"
        UA["User Application"]:::user
    end

    %% SDK Library
    subgraph "SDK Library"
        OSC["OpenseaStreamClient"]:::internal
        CM["Connection Manager"]:::internal
        SM["Subscription Manager"]:::internal
        ED["Event Dispatcher"]:::internal
        UT["Utils Module"]:::internal
    end

    %% External Services
    subgraph "External Services"
        OS["OpenSea Stream Service\n(wss://stream.openseabeta.com/socket)"]:::external
    end

    %% Optional External Services
    subgraph "Optional External"
        DW["Discord Webhook"]:::optional
    end

    %% Project Files
    subgraph "Project Files"
        SP["setup.py"]:::internal
        RQ["requirements.txt"]:::internal
        RD["README.md"]:::internal
        LI["LICENSE"]:::internal
        GI[".gitignore"]:::internal
        IN["__init__.py"]:::internal
    end

    %% Connections
    UA -->|"instantiate & subscribe()"| OSC
    OSC -->|"manages WS lifecycle"| CM
    OSC -->|"tracks subscriptions"| SM
    OSC -->|"dispatches events"| ED
    OSC -->|uses| UT

    CM -->|"connect/authenticate"| OS
    OS -->|"event JSON"| CM
    CM -->|"pass message"| ED

    ED -->|"invoke user callbacks"| UA
    ED -->|"POST payload"| DW

    %% Click Events
    click OSC "https://github.com/jerempjerem/opensea-stream-py/blob/main/opensea-stream/opensea_stream.py"
    click UT "https://github.com/jerempjerem/opensea-stream-py/blob/main/opensea-stream/utils.py"
    click SP "https://github.com/jerempjerem/opensea-stream-py/blob/main/setup.py"
    click RQ "https://github.com/jerempjerem/opensea-stream-py/blob/main/requirements.txt"
    click RD "https://github.com/jerempjerem/opensea-stream-py/blob/main/README.md"
    click LI "https://github.com/jerempjerem/opensea-stream-py/tree/main/LICENSE"
    click GI "https://github.com/jerempjerem/opensea-stream-py/blob/main/.gitignore"
    click IN "https://github.com/jerempjerem/opensea-stream-py/blob/main/opensea-stream/__init__.py"

    %% Styles
    classDef user fill:#c8e6c9,stroke:#2e7d32,stroke-width:1px;
    classDef internal fill:#bbdefb,stroke:#1565c0,stroke-width:1px;
    classDef external fill:#eeeeee,stroke:#424242,stroke-width:1px;
    classDef optional fill:#f0f4c3,stroke:#827717,stroke-width:1px;
```
