# delphiresearch/polynance-ts-client architecture

> Architecture diagram of the GitHub repository delphiresearch/polynance-ts-client, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/delphiresearch/polynance-ts-client
- Repository: https://github.com/delphiresearch/polynance-ts-client

## Overview

##### Project Type and Purpose
- This is an SDK library designed as an aggregation layer for prediction market protocols, meaning it abstracts the complexities of interacting with various prediction market platforms (Polymarket, Limitless, TrueMarket).
- The project’s primary role is to expose a unified client interface that developers can use to retrieve market and event data, subscribe to real-time updates using SSE, and generate candlestick data.

##### Analyzing the File Structure
- Top-Level Files: Notice files such as .gitignore, package.json, tsconfig.json, and README.md that set up the environment, TypeScript configurations, and package details.
- Package Distributions: The presence of polynance_sdk-1.0.0.tgz and polynance_sdk-1.0.1.tgz indicates that packaged versions of this SDK are built and potentially published.
- Source Code Layout:
- The main logic is under the src directory.
- Within src/core, you find client.ts and types.ts, which hint at the central components: the client implementation, which likely handles API calls and business logic, and the types file that defines key data structures (e.g., FillEventData, PredictionMarketEvent, etc.).
- The src/index.ts file likely exports higher-level interfaces to consumers of this library.

##### Elements to Capture
a. Main Components:
- PolynanceClient Component: Represent the primary interface that consumers import and initialize.
- Core Modules:
- Client Module (src/core/client.ts) – The hub responsible for interfacing with the different prediction market protocols.
- Types Module (src/core/types.ts) – Houses type definitions for events, markets, comments, order books, candlestick data, etc.
- Protocol Adapter Simulations: Even if the code doesn’t explicitly break out separate adapter classes, conceptually include components or blocks representing the abstraction layers for each supported protocol (Polymarket, Limitless, TrueMarket).
- Utility/Helper Functions: For example, the generateCandlestickData function, which might be shown as a dedicated utility component.

b. Relationships and Interactions:
- How function calls (API methods) flow from the client into the respective modules and how they return data (for example, detailed event or market information).
- Subscription mechanism for real-time updates via SSE as a data flow path from external SSE sources into the client’s event handlers.

c. Architectural Patterns and Design Principles:
- Abstraction Layer: Emphasize how the SDK abstracts underlying protocol differences.
- Modularity: Highlight the separation between the core client logic and the type definitions/utilities.
- Interface Segregation: Show clear segmentation of API methods that cover distinct functionalities (fetching events, obtaining order books, subscribing to real-time updates, etc.).
- Dependency Handling: Optionally, annotate how external or built-in libraries (e.g., modules handling Server-Sent Events) integrate into the system.

d. Relevant Technologies and Frameworks:
- TypeScript is used across the project (indicated by tsconfig.json), so label components as TypeScript modules.
- Node.js ecosystem: package.json and npm installation instructions point to its usage.
- Server-Sent Events (SSE): Represented in the subscription methods.

##### Final Recommendations
- Avoid overly simplistic grouping; break the system into as many logical components as the project structure and its functionality details allow.

## Diagram (Mermaid)

```mermaid
flowchart TD
    ConsumerApp["Consumer Application"]:::external
    PublicAPI["Public API Interface"]:::api
    PolynanceClient["PolynanceClient"]:::client
    CoreClient["Core - Client Module"]:::client
    CoreTypes["Core - Types & Interfaces"]:::types
    CandlestickUtility["Utility Module: Candlestick Generation"]:::utility
    PolymarketAdapter["Protocol Adapter: Polymarket"]:::protocol
    LimitlessAdapter["Protocol Adapter: Limitless"]:::protocol
    TrueMarketAdapter["Protocol Adapter: TrueMarket"]:::protocol
    SSESource["SSE Data Source"]:::external

    ConsumerApp -->|"initialize"| PublicAPI
    PublicAPI -->|"exports/initializes"| PolynanceClient
    PolynanceClient -->|"APIcalls"| CoreClient
    PolynanceClient -.->|"usestypes"| CoreTypes
    PolynanceClient -->|"getEvent,getMarket,etc."| PolymarketAdapter
    PolynanceClient -->|"getEvent,getMarket,etc."| LimitlessAdapter
    PolynanceClient -->|"getEvent,getMarket,etc."| TrueMarketAdapter
    PolynanceClient -->|"generateCandlestickData"| CandlestickUtility
    SSESource -->|"SSEupdates"| PolynanceClient

    click PolynanceClient "https://github.com/delphiresearch/polynance-ts-client/blob/main/src/core/client.ts"
    click CoreClient "https://github.com/delphiresearch/polynance-ts-client/blob/main/src/core/client.ts"
    click CoreTypes "https://github.com/delphiresearch/polynance-ts-client/blob/main/src/core/types.ts"
    click PublicAPI "https://github.com/delphiresearch/polynance-ts-client/blob/main/src/index.ts"

    classDef client fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef types fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef api fill:#D7BDE2,stroke:#6C3483,stroke-width:2px;
    classDef protocol fill:#A9DFBF,stroke:#196F3D,stroke-width:2px;
    classDef utility fill:#FAD7A0,stroke:#D35400,stroke-width:2px;
    classDef external fill:#F5B7B1,stroke:#943126,stroke-width:2px;
```
