# miguelgrinberg/python-socketio architecture

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

- Interactive diagram: https://gitdiagram.com/miguelgrinberg/python-socketio
- Repository: https://github.com/miguelgrinberg/python-socketio

## Overview

##### Project type and purpose
- This is an open-source Python library (python-socketio) that implements the Socket.IO realtime protocol for both clients and servers.
- It provides sync and async APIs, pluggable managers for pub/sub (Redis, Kafka, ZMQ, Kombu), and adapters for various Python web frameworks (aiohttp, Sanic, FastAPI/ASGI, Tornado, WSGI/Django, etc.).

##### Top-level structure and architectural patterns
- src/socketio: core modules—separate base classes (base_server, base_namespace, base_client, base_manager) and concrete implementations (async_server, server; async_manager, redis_manager, kafka_manager, zmq_manager, kombu_manager).
- Pluggable “Manager” pattern: one manager per pub/sub backend.
- Separate sync vs. async namespaces and servers.
- Adapters/middleware for integration with external frameworks (asgi.py, middleware.py, tornado.py).
- Examples directory showing integration points with clients (sync/async/js) and servers (aiohttp, ASGI, Django, etc.).

##### Key components
a. Clients
- Python sync client / Python async client / JavaScript client
b. Transport layers
- Engine.IO transport (WebSocket / HTTP long-polling)
c. Socket.IO server core
- BaseServer <- Server / AsyncServer
- Namespaces (BaseNamespace / AsyncNamespace)
d. Manager (message broadcasting)
- Default in-memory manager
- RedisManager, KafkaManager, ZmqManager, KombuManager, AiopikaManager, AsyncRedisManager, AsyncPubSubManager
e. Framework adapters
- ASGI middleware (FastAPI, Litestar), aiohttp, Sanic, Tornado, WSGI/Django
f. External services
- Redis, Kafka, ZMQ brokers, RabbitMQ (via Kombu), AMQP (via aiopika)
g. Application code (user namespaces / event handlers)

##### Relationships and data flow
- Client emits event → Engine.IO layer → Server receives packet → Namespace handler processes event → May invoke Manager to broadcast → Manager publishes to external broker(s) or in-memory channel → Other server instances (if clustered) subscribe and receive message via Manager → Namespace on each server instance sends outbound packet via Engine.IO → Client receives.
- Sync vs. Async paths are parallel but use the same conceptual flow, just different event loops.
- Framework adapter wraps the Socket.IO server core and exposes it as, e.g., an ASGI app or a WSGI app.

##### Architectural patterns and technologies
- Layered architecture: Transport / Protocol parsing (packet, msgpack_packet) → Core server → Namespaces → Manager → External pub/sub.
- Dependency injection for the Manager component, enabling horizontal scalability.
- Strategy pattern for sync vs async.
- Adapter pattern for web frameworks.

##### Essential elements
- Clear component names: AsyncServer, Server, BaseManager, RedisManager, etc.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    subgraph "Clients"
        sync_client["Python Sync Client"]:::client
        async_client["Python Async Client"]:::client
        simple_sync_client["Simple Sync Client"]:::client
        simple_async_client["Simple Async Client"]:::client
        js_client["JavaScript Client"]:::client
    end

    %% Transport Layer
    subgraph "Transport Layer"
        json_packet["JSON Packet (Engine.IO)"]:::transport
        msgpack_packet["MessagePack Packet"]:::transport
    end

    %% Core Server
    subgraph "Core Server"
        subgraph "Sync Components"
            base_server["BaseServer"]:::core
            server["Server"]:::core
            base_namespace["BaseNamespace"]:::core
            namespace["Namespace"]:::core
        end
        subgraph "Async Components"
            async_server["AsyncServer"]:::core
            async_base_namespace["BaseNamespace"]:::core
            async_namespace["AsyncNamespace"]:::core
        end
    end

    %% Managers / Backends
    subgraph "Managers / Backends"
        base_manager["BaseManager"]:::manager
        in_memory_manager["InMemory Manager"]:::manager
        redis_manager["Redis Manager"]:::manager
        async_redis_manager["Async Redis Manager"]:::manager
        kafka_manager["Kafka Manager"]:::manager
        zmq_manager["ZMQ Manager"]:::manager
        kombu_manager["Kombu Manager"]:::manager
        pubsub_manager["Pub/Sub Manager"]:::manager
        async_pubsub_manager["Async Pub/Sub Manager"]:::manager
        async_aiopika_manager["Async Aiopika Manager"]:::manager
    end

    %% Framework Adapters
    subgraph "Framework Adapters"
        asgi_adapter["ASGI Adapter"]:::adapter
        wsgi_adapter["WSGI/Django Adapter"]:::adapter
        tornado_adapter["Tornado Adapter"]:::adapter
    end

    %% External Services
    subgraph "External Services"
        redis_service["Redis"]:::service
        kafka_service["Kafka"]:::service
        zmq_service["ZMQ"]:::service
        rabbitmq_service["RabbitMQ"]:::service
        amqp_service["AMQP"]:::service
    end

    %% Data Flows
    sync_client -->|"Socket.IO packet"| json_packet
    simple_sync_client -->|"Socket.IO packet"| json_packet
    async_client -->|"Socket.IO packet"| msgpack_packet
    simple_async_client -->|"Socket.IO packet"| msgpack_packet
    js_client -->|"Socket.IO packet"| json_packet

    json_packet -->|"decode"| base_server
    msgpack_packet -->|"decode"| async_server

    base_server -->|"uses"| namespace
    server -->|"extends"| base_server
    namespace -->|"handles events"| base_manager

    async_server -->|"uses"| async_namespace
    async_server -->|"extends"| server
    async_namespace -->|"handles events"| base_manager

    base_manager -->|"default"| in_memory_manager
    base_manager -->|"strategy"| redis_manager
    base_manager -->|"strategy"| async_redis_manager
    base_manager -->|"strategy"| kafka_manager
    base_manager -->|"strategy"| zmq_manager
    base_manager -->|"strategy"| kombu_manager
    base_manager -->|"strategy"| pubsub_manager
    base_manager -->|"strategy"| async_pubsub_manager
    base_manager -->|"strategy"| async_aiopika_manager

    in_memory_manager -->|"broadcast"| base_server
    redis_manager -->|"publish"| redis_service
    async_redis_manager -->|"publish"| redis_service
    kafka_manager -->|"publish"| kafka_service
    zmq_manager -->|"publish"| zmq_service
    kombu_manager -->|"publish"| rabbitmq_service
    pubsub_manager -->|"publish"| kafka_service
    async_pubsub_manager -->|"publish"| kafka_service
    async_aiopika_manager -->|"publish"| amqp_service

    base_server -->|"emit"| json_packet
    async_server -->|"emit"| msgpack_packet
    json_packet -->|"Socket.IO packet"| sync_client
    msgpack_packet -->|"Socket.IO packet"| async_client

    asgi_adapter -->|"wraps"| base_server
    wsgi_adapter -->|"wraps"| base_server
    tornado_adapter -->|"wraps"| async_server

    %% Click Events
    click sync_client "https://github.com/miguelgrinberg/python-socketio/blob/main/src/socketio/client.py"
    click async_client "https://github.com/miguelgrinberg/python-socketio/blob/main/src/socketio/async_client.py"
    click simple_sync_client "https://github.com/miguelgrinberg/python-socketio/blob/main/src/socketio/simple_client.py"
    click simple_async_client "https://github.com/miguelgrinberg/python-socketio/blob/main/src/socketio/async_simple_client.py"
    click json_packet "https://github.com/miguelgrinberg/python-socketio/blob/main/src/socketio/packet.py"
    click msgpack_packet "https://github.com/miguelgrinberg/python-socketio/blob/main/src/socketio/msgpack_packet.py"
    click base_server "https://github.com/miguelgrinberg/python-socketio/blob/main/src/socketio/base_server.py"
    click server "https://github.com/miguelgrinberg/python-socketio/blob/main/src/socketio/server.py"
    click async_server "https://github.com/miguelgrinberg/python-socketio/blob/main/src/socketio/async_server.py"
    click base_namespace "https://github.com/miguelgrinberg/python-socketio/blob/main/src/socketio/base_namespace.py"
    click namespace "https://github.com/miguelgrinberg/python-socketio/blob/main/src/socketio/namespace.py"
    click async_namespace "https://github.com/miguelgrinberg/python-socketio/blob/main/src/socketio/async_namespace.py"
    click base_manager "https://github.com/miguelgrinberg/python-socketio/blob/main/src/socketio/base_manager.py"
    click in_memory_manager "https://github.com/miguelgrinberg/python-socketio/blob/main/src/socketio/manager.py"
    click redis_manager "https://github.com/miguelgrinberg/python-socketio/blob/main/src/socketio/redis_manager.py"
    click async_redis_manager "https://github.com/miguelgrinberg/python-socketio/blob/main/src/socketio/async_redis_manager.py"
    click kafka_manager "https://github.com/miguelgrinberg/python-socketio/blob/main/src/socketio/kafka_manager.py"
    click zmq_manager "https://github.com/miguelgrinberg/python-socketio/blob/main/src/socketio/zmq_manager.py"
    click kombu_manager "https://github.com/miguelgrinberg/python-socketio/blob/main/src/socketio/kombu_manager.py"
    click pubsub_manager "https://github.com/miguelgrinberg/python-socketio/blob/main/src/socketio/pubsub_manager.py"
    click async_pubsub_manager "https://github.com/miguelgrinberg/python-socketio/blob/main/src/socketio/async_pubsub_manager.py"
    click async_aiopika_manager "https://github.com/miguelgrinberg/python-socketio/blob/main/src/socketio/async_aiopika_manager.py"
    click asgi_adapter "https://github.com/miguelgrinberg/python-socketio/blob/main/src/socketio/asgi.py"
    click wsgi_adapter "https://github.com/miguelgrinberg/python-socketio/blob/main/src/socketio/middleware.py"
    click tornado_adapter "https://github.com/miguelgrinberg/python-socketio/blob/main/src/socketio/tornado.py"

    %% Styles
    classDef client fill:#ADD8E6,stroke:#000;
    classDef transport fill:#90EE90,stroke:#000;
    classDef core fill:#FFFF99,stroke:#000;
    classDef manager fill:#FFA500,stroke:#000;
    classDef adapter fill:#D8BFD8,stroke:#000;
    classDef service fill:#FF6347,stroke:#000;
    class sync_client,async_client,simple_sync_client,simple_async_client,js_client client
    class json_packet,msgpack_packet transport
    class base_server,server,namespace,base_namespace,async_server,async_namespace,async_base_namespace core
    class base_manager,in_memory_manager,redis_manager,async_redis_manager,kafka_manager,zmq_manager,kombu_manager,pubsub_manager,async_pubsub_manager,async_aiopika_manager manager
    class asgi_adapter,wsgi_adapter,tornado_adapter adapter
    class redis_service,kafka_service,zmq_service,rabbitmq_service,amqp_service service
```
