# shoonya-dev/shoonyaapi-py architecture

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

- Interactive diagram: https://gitdiagram.com/shoonya-dev/shoonyaapi-py
- Repository: https://github.com/shoonya-dev/shoonyaapi-py

## Overview

##### Project Type & Purpose
- It’s a Python client-library (wrapper/facade) for Shoonya’s OMS REST API + real-time WebSocket feed.
- Provides a unified interface (api_helper.py → ShoonyaApiPy) so downstream scripts/apps can log in, query data, place orders, and subscribe to market/order feeds without dealing with raw HTTP or WS details.

##### File-Structure Analysis
- Top-level:
– api_helper.py: core connector class (ShoonyaApiPy).
– cred.yml: external credentials/config.
– example_market.py / example_orders.py: sample client usage.
– test_api.py + tests/*: unit/integration tests exercising each API method.
– dist/: packaged wheel for distribution.
– requirements.txt: dependencies (e.g., requests, websocket-client, PyYAML).
- No frontend; purely library + examples + tests + packaging.

##### README Insights
- Describes all REST methods (login, logout, place_order, modify_order, …) and WebSocket subscribe flows.
- Emphasizes one WS connection for both market tick feed and order updates.
- Shows sample code for builder pattern: instantiate ShoonyaApiPy, configure endpoints, login, then call methods or start_websocket + subscribe.

##### Main Components & Relationships

[ Client Application ]
- example_market.py, example_orders.py, any downstream script
↘ calls
[ Shoonya Python Wrapper (api_helper.py) ]
- ShoonyaApiPy class
- Loads cred.yml → holds userid, vendor_code, api_secret, URLs
- Uses HTTP client to invoke Shoonya REST endpoints
- Uses WebSocket client to open a single socket for tick + order feeds
↘ HTTP JSON requests/responses ↔
[ Shoonya REST API Endpoints ] (external service)
↗ WebSocket JSON streams ↔
[ Shoonya WebSocket Server ] (external feed)

Supporting components:
- [Configuration Store] (cred.yml) → used by wrapper on init
- [Local Cache / Example Data] (tests/realtime_excel_feed.xlsx) for tests
- [Test Suite] (test_api.py + tests/) → invokes wrapper methods, asserts JSON responses
- [Distribution] (dist/*.whl) ← built from code + requirements

##### Architectural Patterns & Design Principles
- Facade Pattern: ShoonyaApiPy hides raw HTTP/WS complexity behind simple verbs.
- Single Responsibility: api_helper.py handles comms; examples handle business usage; tests handle validation.
- Dependency Injection: endpoints & creds loaded from YAML; tests can swap in mocks.
- Event-Driven: WebSocket callbacks for market and order updates.

##### Essential Details to Capture
- Single WebSocket connection for two callback streams (market + order).
- How the wrapper maintains session token (susertoken/jKey) in headers or WS handshake.
- The requirement to HTTP‐login before invoking any other REST methods.
- Local credential file separation (no hard-coding).
- Test harness invoking each REST/WS method ensures coverage.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Applications
    subgraph "Client Applications" 
        direction TB
        ExampleMarket["example_market.py"]:::local
        ExampleOrders["example_orders.py"]:::local
    end

    %% Configuration Store
    Config["cred.yml"]:::config

    %% Wrapper Facade
    Wrapper["api_helper.py\n(ShoonyaApiPy)"]:::local

    %% Dependencies
    Requirements["requirements.txt"]:::local

    %% Test Suite
    subgraph "Test Suite" 
        direction TB
        TestAPI["test_api.py"]:::local
        TestsDir["tests/"]:::local
        RealtimeExcel["tests/realtime_excel_feed.xlsx"]:::local
    end

    %% Distribution Artifacts
    subgraph "Distribution" 
        direction TB
        DistDir["dist/"]:::dist
        DistWheel["NorenRestApi-0.0.30-py2.py3-none-any.whl"]:::dist
    end

    %% External Services
    subgraph "External Services"
        direction TB
        RESTAPI["REST API Endpoints"]:::external
        WS["WebSocket Server"]:::external
    end

    %% Relationships
    ExampleMarket -->|method calls| Wrapper
    ExampleOrders -->|method calls| Wrapper
    Wrapper -->|file load| Config
    Wrapper -->|reads deps| Requirements
    Wrapper -->|HTTP JSON request/response| RESTAPI
    Wrapper -->|WebSocket JSON stream| WS
    TestAPI -->|invokes methods| Wrapper
    TestsDir -->|uses data| RealtimeExcel
    TestsDir -->|invokes tests| Wrapper
    DistWheel -->|built from| Wrapper
    DistWheel -->|includes| Requirements

    %% Click Events
    click ExampleMarket "https://github.com/shoonya-dev/shoonyaapi-py/blob/master/example_market.py"
    click ExampleOrders "https://github.com/shoonya-dev/shoonyaapi-py/blob/master/example_orders.py"
    click Wrapper "https://github.com/shoonya-dev/shoonyaapi-py/blob/master/api_helper.py"
    click Config "https://github.com/shoonya-dev/shoonyaapi-py/blob/master/cred.yml"
    click TestAPI "https://github.com/shoonya-dev/shoonyaapi-py/blob/master/test_api.py"
    click TestsDir "https://github.com/shoonya-dev/shoonyaapi-py/tree/master/tests/"
    click RealtimeExcel "https://github.com/shoonya-dev/shoonyaapi-py/blob/master/tests/realtime_excel_feed.xlsx"
    click Requirements "https://github.com/shoonya-dev/shoonyaapi-py/blob/master/requirements.txt"
    click DistDir "https://github.com/shoonya-dev/shoonyaapi-py/tree/master/dist/"
    click DistWheel "https://github.com/shoonya-dev/shoonyaapi-py/blob/master/dist/NorenRestApi-0.0.30-py2.py3-none-any.whl"

    %% Styles
    classDef local fill:#a2f5a2,stroke:#333,stroke-width:1px
    classDef external fill:#a2c5f5,stroke:#333,stroke-width:1px
    classDef config fill:#f5cba2,stroke:#333,stroke-width:1px
    classDef dist fill:#d3d3d3,stroke:#333,stroke-width:1px
```
