# harshendram/orchestratingarbbot-probo-polymarket architecture

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

- Interactive diagram: https://gitdiagram.com/harshendram/orchestratingarbbot-probo-polymarket
- Repository: https://github.com/harshendram/orchestratingarbbot-probo-polymarket

## Overview

##### Project Type and Purpose
- This is a single-process, TypeScript-based arbitrage bot that continuously polls two prediction-market APIs (Probo in INR and Polymarket in USD), detects cross-currency price discrepancies, and executes paired trades to lock in risk-free profit.

##### File Structure
- Top-level entrypoints:
- **cli.ts** – command-line interface for “start”, “check”, “dry-run”, custom polling intervals
- **index.ts** – main orchestration, sets up scheduler, injects config, invokes core logic
- API integrations:
- **probo.ts** – wrapper for Probo REST API (INR-denominated orderbook)
- **polymarket.ts** – wrapper for Polymarket CLOB/REST API (USD orderbook + signer for blockchain)
- Configuration:
- **config.ts** – loads and validates environment variables (API keys, RPC URL, thresholds, DB path, dry-run flag)
- Core logic & types:
- **types.ts** – TS type definitions (Orderbook, Opportunity, TradeResult)
- **utils/helpers.ts** – conversion (USD→INR), profit calculation, threshold checks
- Execution and persistence:
- **utils/database.ts** – SQLite (or file) DB operations for history
- **utils/logger.ts** – structured logging (“debug”, “info”, “warn”, “error”)
- Testing and resilience:
- **mocks/** – mock implementations for probo, polymarket, ethers
- **index.test.ts** – end-to-end test harness with Jest
- Other: **tsconfig.json**, **bun.lock** / **package.json**, **.env.sample**, **package-lock.json**

##### README for Architecture Insights
- Two embedded PNGs in **utils/assets/** illustrate (a) component interactions, (b) logic flow.
- High-level steps: fetch → convert → analyze → execute → repeat.
- Mentions retry logic, rate limiting, dry-run mode.

##### Main Components & Interactions (
A. **Scheduler / CLI** (cli.ts → index.ts)
- Triggers polling at `--interval` or default loop
B. **Configuration Manager** (config.ts)
- Reads `.env`, injects into all modules
C. **Market Data Collectors**
1. Probo Module (probo.ts) → Probo REST API
2. Polymarket Module (polymarket.ts) → Polymarket CLOB/REST + Ethereum JSON-RPC
- Both pass raw orderbook objects to the analyzer
D. **Currency Converter** (helpers.ts)
- Applies `DOLLAR_PRICE_INR` to normalize USD prices to INR
E. **Opportunity Analyzer** (core logic in index.ts + helpers.ts)
- Computes combined YES/NO cost vs. 100%
- Checks against `EXPECTED_ARB_PERCENT_MIN`
F. **Order Executor** (polymarket.ts + probo.ts wrappers + ethers SDK)
- Places hedged orders on both platforms simultaneously
- Honors `DRY_RUN` flag
- Implements retry logic & rate limiter (in helpers or wrapper layers)
G. **Persistence Layer** (database.ts)
- Records all candidate opportunities and executed trades to `DB_PATH`
H. **Logging** (logger.ts)
- Emits detailed logs at each step

##### Architectural Patterns & Principles
- **Modular Layers**: clear separation (CLI → Config → Data Collection → Conversion → Analysis → Execution → Persistence → Logging)
- **Single Responsibility** per module
- **Dependency Injection** via `config.ts`
- **Resilience**: rate limiting + retry wrappers around external-API calls
- **Testability**: mocks for API & blockchain interactions

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Config & Entrypoint
    CLI["CLI / Scheduler<br/>(cli.ts)"]:::config
    ConfigMgr["Configuration Manager<br/>(config.ts)"]:::config
    Index["Main Orchestration & Analyzer<br/>(index.ts)"]:::internal

    %% Data Collection Modules
    ProboModule["Probo Module<br/>(probo.ts)"]:::internal
    PolyModule["Polymarket Module<br/>(polymarket.ts)"]:::internal

    %% Business Logic
    Types["Types Definitions<br/>(types.ts)"]:::internal
    Helpers["Converter & Opportunity Logic<br/>(utils/helpers.ts)"]:::internal

    %% Execution
    Executor["Order Executor<br/>(probo.ts & polymarket.ts)"]:::internal

    %% Persistence & Logging
    DB["Persistence Layer (SQLite)<br/>(utils/database.ts)"]:::db
    Logger["Structured Logging<br/>(utils/logger.ts)"]:::internal

    %% External Services
    ProboAPI["Probo REST API (HTTPS)"]:::external
    PolymarketAPI["Polymarket CLOB/REST API (HTTPS)"]:::external
    EthRPC["Ethereum JSON-RPC"]:::external

    %% Testing & Assets
    Mocks["API & Blockchain Mocks<br/>(mocks/)"]:::external
    Test["End-to-End Test Harness<br/>(index.test.ts)"]:::external
    Assets["Diagram Assets<br/>(utils/assets/)"]:::external

    %% Relationships
    CLI -->|triggers| Index
    CLI -->|--interval/dry-run| ConfigMgr
    ConfigMgr -->|injects config| Index

    Index -->|fetch orderbook| ProboModule
    Index -->|fetch orderbook| PolyModule
    ProboModule -->|HTTP/JSON<br/>retry&rate-limit| ProboAPI
    ProboAPI -->|JSON| ProboModule
    PolyModule -->|HTTP/JSON<br/>retry&rate-limit| PolymarketAPI
    PolymarketAPI -->|JSON| PolyModule
    PolyModule -->|JSON-RPC| EthRPC
    EthRPC -->|response| PolyModule

    ProboModule -->|orderbook| Index
    PolyModule -->|orderbook| Index

    Index -->|uses types| Types
    Index -->|uses conversion| Helpers
    Helpers -->|normalized prices| Index

    Index -->|opportunity data| Executor
    Executor -->|place orders| ProboModule
    Executor -->|place orders| PolyModule
    ProboModule -->|HTTP/JSON<br/>retry&rate-limit| ProboAPI
    PolyModule -->|HTTP/JSON<br/>retry&rate-limit| PolymarketAPI
    PolyModule -->|JSON-RPC| EthRPC

    Executor -->|record trade| DB
    Executor -->|log details| Logger
    Index -->|log process| Logger
    ProboModule -->|log| Logger
    PolyModule -->|log| Logger

    %% Testing & Assets
    Mocks -->|overrides| ProboModule
    Mocks -->|overrides| PolyModule
    Test -->|tests| Index
    Assets -->|illustrations| Index

    %% Click Events
    click CLI "https://github.com/harshendram/orchestratingarbbot-probo-polymarket/blob/main/cli.ts"
    click ConfigMgr "https://github.com/harshendram/orchestratingarbbot-probo-polymarket/blob/main/config.ts"
    click Index "https://github.com/harshendram/orchestratingarbbot-probo-polymarket/blob/main/index.ts"
    click ProboModule "https://github.com/harshendram/orchestratingarbbot-probo-polymarket/blob/main/probo.ts"
    click PolyModule "https://github.com/harshendram/orchestratingarbbot-probo-polymarket/blob/main/polymarket.ts"
    click Types "https://github.com/harshendram/orchestratingarbbot-probo-polymarket/blob/main/types.ts"
    click Helpers "https://github.com/harshendram/orchestratingarbbot-probo-polymarket/blob/main/utils/helpers.ts"
    click Executor "https://github.com/harshendram/orchestratingarbbot-probo-polymarket/blob/main/probo.ts"
    click DB "https://github.com/harshendram/orchestratingarbbot-probo-polymarket/blob/main/utils/database.ts"
    click Logger "https://github.com/harshendram/orchestratingarbbot-probo-polymarket/blob/main/utils/logger.ts"
    click Mocks "https://github.com/harshendram/orchestratingarbbot-probo-polymarket/tree/main/mocks/"
    click Test "https://github.com/harshendram/orchestratingarbbot-probo-polymarket/blob/main/index.test.ts"
    click Assets "https://github.com/harshendram/orchestratingarbbot-probo-polymarket/tree/main/utils/assets/"

    %% Styles
    classDef internal fill:#ccffcc,stroke:#333,stroke-width:1px
    classDef external fill:#ccf0ff,stroke:#333,stroke-width:1px
    classDef db fill:#ffdd99,stroke:#333,stroke-width:1px
    classDef config fill:#dddddd,stroke:#333,stroke-width:1px
```
