# sabjorn/numpysocket architecture

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

- Interactive diagram: https://gitdiagram.com/sabjorn/numpysocket
- Repository: https://github.com/sabjorn/numpysocket

## Overview

##### Project type and purpose
- This is an open-source Python library (“NumpySocket”) that extends the built-in socket.socket class to transmit and receive NumPy arrays over TCP/IP with the same method names (`sendall`, `recv`) as a normal socket.

##### File structure
- numpysocket/
- __init__.py
- numpysocket.py   ← core implementation of the subclass
- examples/
- Simple (simple_client.py, simple_server.py)
- OpenCV (cv_client.py, cv_server.py, requirements.txt)
- UnixSocket (local socket examples)
- tests/
- unit tests and an integration test
- CI & packaging
- GitHub Actions workflows under .github/workflows/
- pyproject.toml, uv.lock, LICENSE, README.md, .pre-commit-config.yaml

##### README for additional insights
- Clearly describes the three overridden methods (`sendall`, `recv`) and usage examples (Simple and OpenCV).
- Mentions known issue with buffer sizing.
- Provides install instructions and development workflow using “uv.”

a. Main components
- NumpySocket Library – the subclass of socket.socket
- Python Standard Library Socket – the underlying transport
- NumPy – the array representation and buffer provider
- Client Applications – e.g. Simple client, OpenCV client
- Server Applications – e.g. Simple server, OpenCV server
- Test Suite – unit and integration tests (pytest)
- CI/CD Pipeline – GitHub Actions workflows for testing and publishing
- Package Registry (PyPI) – target for publication

b. Relationships and interactions
1. At runtime:
2. In development:
– Source changes → unit tests invoke methods directly → integration test spins up server & client → CI workflow triggers these tests → on passing, publish job uses pyproject to build and upload package.

c. Architectural patterns and design principles
– Subclassing / inheritance: extending socket.socket without modifying original code.
– Single responsibility: library focuses purely on array transport, tests and examples separate.
– CI/CD best practices: automated testing and publishing.

d. Key technologies and libraries
– Python 3.x
– NumPy
– socket (std lib)
– pytest (tests)
– GitHub Actions (CI)
– uv (development tooling)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Runtime components
    subgraph "Runtime Flow"
        direction TB
        subgraph "Client Applications" 
            direction TB
            SC["Simple Client"]:::runtime
            click SC "https://github.com/sabjorn/numpysocket/blob/main/examples/Simple/simple_client.py"
            OC["OpenCV Client"]:::runtime
            click OC "https://github.com/sabjorn/numpysocket/blob/main/examples/OpenCV/cv_client.py"
            UC["UnixSocket Client"]:::runtime
            click UC "https://github.com/sabjorn/numpysocket/blob/main/examples/UnixSocket/unix_socket_client.py"
        end

        NSC["NumpySocket (sendall override)"]:::runtime
        click NSC "https://github.com/sabjorn/numpysocket/blob/main/numpysocket/numpysocket.py"
        PS_C["Python StdLib Socket (client)"]:::runtime
        NET["Network Transport"]:::runtime
        class NET external
        PS_S["Python StdLib Socket (server)"]:::runtime
        NS_S["NumpySocket (recv override)"]:::runtime
        click NS_S "https://github.com/sabjorn/numpysocket/blob/main/numpysocket/numpysocket.py"
        subgraph "Server Applications"
            direction TB
            SS["Simple Server"]:::runtime
            click SS "https://github.com/sabjorn/numpysocket/blob/main/examples/Simple/simple_server.py"
            OS["OpenCV Server"]:::runtime
            click OS "https://github.com/sabjorn/numpysocket/blob/main/examples/OpenCV/cv_server.py"
            US["UnixSocket Server"]:::runtime
            click US "https://github.com/sabjorn/numpysocket/blob/main/examples/UnixSocket/unix_socket_server.py"
        end
    end

    SC -->|"sendall(np.ndarray)\nserialize: dtype,shape,length"| NSC
    NSC -->|"delegate send raw bytes"| PS_C
    PS_C -->|TCP/IP| NET
    NET -->|TCP/IP| PS_S
    PS_S -->|"base recv raw bytes"| NS_S
    NS_S -->|"deserialize→np.ndarray"| SS

    %% Development components
    subgraph "Development Flow"
        direction TB
        SR["Source Repository"]:::dev
        subgraph "CI/CD Pipeline"
            direction TB
            CT["Test Workflow"]:::dev
            click CT "https://github.com/sabjorn/numpysocket/blob/main/.github/workflows/python-test.yml"
            PT["Publish Workflow"]:::dev
            click PT "https://github.com/sabjorn/numpysocket/blob/main/.github/workflows/python-publish.yml"
        end
        subgraph "Tests"
            direction TB
            UT["Unit Tests"]:::dev
            click UT "https://github.com/sabjorn/numpysocket/blob/main/tests/test_numpysocket.py"
            IT["Integration Tests"]:::dev
            click IT "https://github.com/sabjorn/numpysocket/blob/main/tests/test_numpysocket_integration.py"
        end
        PC["Packaging Config\n(pyproject.toml)"]:::config
        click PC "https://github.com/sabjorn/numpysocket/blob/main/pyproject.toml"
        LOCK["Dev Lockfile\n(uv.lock)"]:::config
        click LOCK "https://github.com/sabjorn/numpysocket/blob/main/uv.lock"
        DOC["README.md"]:::config
        click DOC "https://github.com/sabjorn/numpysocket/blob/main/README.md"
        LIC["LICENSE"]:::config
        click LIC "https://github.com/sabjorn/numpysocket/tree/main/LICENSE"
        PRE["Pre-commit Config"]:::config
        click PRE "https://github.com/sabjorn/numpysocket/blob/main/.pre-commit-config.yaml"
        GI[".gitignore"]:::config
        click GI "https://github.com/sabjorn/numpysocket/blob/main/.gitignore"
        PYPI["PyPI Registry"]:::external
    end

    SR --> CT
    CT --> UT
    CT --> IT
    IT --> PT
    PT --> PYPI
    SR --> PC
    SR --> LOCK
    SR --> DOC
    SR --> LIC
    SR --> PRE
    SR --> GI

    %% Styles
    classDef runtime fill:#e0f7fa,stroke:#006064,color:#004d40
    classDef dev fill:#e8f5e9,stroke:#1b5e20,color:#2e7d32
    classDef external fill:#fff3e0,stroke:#e65100,color:#bf360c
    classDef config fill:#f1f8e9,stroke:#33691e,color:#1b5e20
```
