# is0tope/3d_order_book architecture

> Architecture diagram of the GitHub repository is0tope/3d_order_book, 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/is0tope/3d_order_book
- Repository: https://github.com/is0tope/3d_order_book

## Overview

##### Project Type and Purpose
- This is a front-end focused application for visualizing crypto market order book data in 3D.
- It uses live feeds from various crypto exchanges (Binance, BitMEX, Kraken) to display order depth and orders in an interactive 3D visualization.
- The README points to a blog post for context, emphasizing the visualization aspect.

##### File Structure
- Top-Level Files:
- Configuration files (package.json, tsconfig.json, webpack.config.js, postcss.config.js, tailwind.config.js) denote a modern JavaScript/TypeScript web application.
- Public directory with index.html holds the entry point for the web interface.
- Source Directory (src):
- Components like BookAnimation.ts, Gui.ts, L2Book.ts, and TradeIndicator.ts represent key front-end modules.
- FeedManager.ts coordinates data-related functionality.
- The feedhandlers folder contains implementation for various exchanges (BinanceFeedHandler.ts, BitMEXFeedHandler.ts, KrakenFeedHandler.ts) and a base Feedhandler.ts, suggesting an extensible design for handling different data sources.
- Additional modules (get-instruments.ts, instruments.json, instruments.ts) manage instrument-related data used to determine which order books to display.

##### Architectural Breakdown
a. Main Components:
- UI Layer: Represented by index.html and Gui.ts that render the user interface elements.
- Visualization Module: BookAnimation.ts for rendering the 3D order book.
- Order Book Management: L2Book.ts to manage Level 2 order book data.
- Trading Indicators: TradeIndicator.ts adds dynamic visual cues for market activity.
- Data Feed Processing: FeedManager.ts to handle incoming data, orchestrate updates, and delegate to appropriate feed handlers.
- Feed Handlers: Under the feedhandlers directory. Each handler (BinanceFeedHandler, BitMEXFeedHandler, KrakenFeedHandler) pertains to a specific crypto exchange connection.
- Instruments & Configuration: Scripts like get-instruments.ts along with instruments.json and instruments.ts to load and configure market instruments for visualization.

b. Relationships and Interactions:
- The GUI (Gui.ts) interacts closely with the BookAnimation for display purposes.
- FeedManager receives live data, then distributes it to relevant components such as L2Book and TradeIndicator.
- Each feed handler is a modular component that abstracts the connection details to its specific exchange.
- The instruments module provides configuration or static data that Benchmarks the available market instruments, feeding into how information is processed by the UI and visualization layers.

c. Architectural Patterns and Design Principles:
- Modular design: Separation between data feed logic and visual rendering allows independent development and testing.
- Extensibility: The feedhandlers subdirectory indicates a pattern for easily adding new data sources.
- Frontend specialization: With a clear separation between static assets (HTML, CSS) and dynamic script-driven modules (TypeScript files).

d. Relevant Technologies, Frameworks, and Libraries:
- TypeScript for type safety and development.
- Webpack as a module bundler.
- Tailwind CSS and PostCSS for styling.
- Likely some 3D transformation libraries for the BookAnimation (although not explicitly mentioned, the name implies a 3D graphics component).

##### Elements
- Use clear labels for components such as "UI Layer", "Visualization Engine", "Order Book Manager", "Feed Manager", and specific feed handlers (Binance, BitMEX, Kraken).
- Optionally, include a note indicating external dependencies, such as crypto market APIs accessed by feed handlers.

- index.html (entry point)
- Gui.ts (UI components)
- style.css (styling)
- FeedManager.ts at the center, connecting with the external “crypto feed APIs” via:
- BinanceFeedHandler.ts
- BitMEXFeedHandler.ts
- KrakenFeedHandler.ts
c. “Business Logic / Visualization” region:
- L2Book.ts for processing order book data.
- BookAnimation.ts for 3D visual rendering.
- TradeIndicator.ts for conveying market signals.
- get-instruments.ts, instruments.json, instruments.ts feeding data into both FeedManager and GUI.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Browser/Client UI
    subgraph "Browser/Client UI"
        UIHTML["index.html"]
        UIGui["Gui.ts"]
        UIStyle["style.css"]
    end

    %% Configuration
    subgraph "Configuration"
        GetInstruments["get-instruments.ts"]
        InstrumentsJSON["instruments.json"]
        InstrumentsTS["instruments.ts"]
    end

    %% Data Feed Processing
    subgraph "Data Feed Processing"
        Binance["BinanceFeedHandler.ts"]
        BitMEX["BitMEXFeedHandler.ts"]
        Kraken["KrakenFeedHandler.ts"]
        FeedManager["FeedManager.ts"]
        
        Binance --> FeedManager
        BitMEX --> FeedManager
        Kraken --> FeedManager
    end

    %% Business Logic & Visualization
    subgraph "Business Logic & Visualization"
        OrderBook["L2Book.ts"]
        TradeIndicator["TradeIndicator.ts"]
        VisBookAnim["BookAnimation.ts"]
        
        FeedManager --> OrderBook
        FeedManager --> TradeIndicator
        OrderBook --> VisBookAnim
        TradeIndicator --> VisBookAnim
        UIGui --> VisBookAnim
    end

    %% Configuration feeds into FeedManager and GUI
    GetInstruments --> FeedManager
    InstrumentsJSON --> FeedManager
    InstrumentsTS --> FeedManager

    GetInstruments --> UIGui
    InstrumentsJSON --> UIGui
    InstrumentsTS --> UIGui

    %% Click Events
    click UIHTML "https://github.com/is0tope/3d_order_book/blob/master/public/index.html"
    click UIGui "https://github.com/is0tope/3d_order_book/blob/master/src/Gui.ts"
    click UIStyle "https://github.com/is0tope/3d_order_book/blob/master/src/style.css"
    click VisBookAnim "https://github.com/is0tope/3d_order_book/blob/master/src/BookAnimation.ts"
    click OrderBook "https://github.com/is0tope/3d_order_book/blob/master/src/L2Book.ts"
    click TradeIndicator "https://github.com/is0tope/3d_order_book/blob/master/src/TradeIndicator.ts"
    click FeedManager "https://github.com/is0tope/3d_order_book/blob/master/src/FeedManager.ts"
    click Binance "https://github.com/is0tope/3d_order_book/blob/master/src/feedhandlers/BinanceFeedHandler.ts"
    click BitMEX "https://github.com/is0tope/3d_order_book/blob/master/src/feedhandlers/BitMEXFeedHandler.ts"
    click Kraken "https://github.com/is0tope/3d_order_book/blob/master/src/feedhandlers/KrakenFeedHandler.ts"
    click GetInstruments "https://github.com/is0tope/3d_order_book/blob/master/src/get-instruments.ts"
    click InstrumentsJSON "https://github.com/is0tope/3d_order_book/blob/master/src/instruments.json"
    click InstrumentsTS "https://github.com/is0tope/3d_order_book/blob/master/src/instruments.ts"

    %% Styles
    classDef ui fill:#a2d2ff,stroke:#000,stroke-width:2px;
    classDef viz fill:#ffadad,stroke:#000,stroke-width:2px;
    classDef feed fill:#ffd6a5,stroke:#000,stroke-width:2px;
    classDef feedhandler fill:#fdffb6,stroke:#000,stroke-width:2px;
    classDef config fill:#caffbf,stroke:#000,stroke-width:2px;

    class UIHTML,UIGui,UIStyle ui;
    class VisBookAnim,OrderBook,TradeIndicator viz;
    class FeedManager feed;
    class Binance,BitMEX,Kraken feedhandler;
    class GetInstruments,InstrumentsJSON,InstrumentsTS config;
```
