# akenshaw/flowsurface-web architecture

> Architecture diagram of the GitHub repository akenshaw/flowsurface-web, 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/akenshaw/flowsurface-web
- Repository: https://github.com/akenshaw/flowsurface-web

## Overview

##### Main Components
- Data Source & Connectivity:
- wsBinance.js – This file is responsible for setting up a websocket connection to Binance. It streams live data (orderbook and kline information) and also incorporates trades (managed by the buffer).
- connectorUtils.js – Likely a helper module that encapsulates details of connecting, parsing, or handling websocket data.
- Data Aggregation & Processing:
- canvasAggr.js – Acts as the core aggregator that takes data from the websocket streams (orderbook, kline, and trades buffer) and processes it. The README explains that the data streams (including grouped exchange data) are processed here for rendering.
- Main processing flow – The README describes how the controller receives three streams (orderbook, latest kline, trades buffer) and passes them to the canvas instance. This includes grouping (footprint instance, volume, CVD, and OI components) based on specific tick size multipliers.
- Presentation & Rendering:
- index.html (and the version in dist/index.html) – The HTML structure contains the canvas element where the 2D rendering takes place.
- style.css and asset files (e.g., index-paYHrqP6.css) – Responsible for styling the UI.
- main.js – Likely the entry point that initializes the data connection, binds the aggregation process, and triggers the rendering.
- Build & Configuration:
- vite.config.js, package.json, package-lock.json – These indicate the build system (Vite) that is used to bundle and serve the application assets.

##### Relationships and Interactions
- The Aggregation/Controller logic collects three distinct streams: orderbook updates, 1-minute klines, and a trades buffer (populated by incoming websocket data).

##### Architectural Patterns and Technologies
- The pattern is essentially a reactive, client-side data processing pipeline where data flows from WebSocket streams → Aggregation & Business Logic (processing, grouping data) → Rendering on a canvas UI.
- Technologies involved include JavaScript (ES modules), a bundler/development server (Vite), and standard HTML/CSS for the UI layer.
- Although not explicitly separated into frontend and backend, the nature of the project (working entirely in the browser) means that all layers are integrated into a single-page application.

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Data Source & Connectivity"
        wsBinance["Binance WS Connector (wsBinance.js)"]
        connectorUtils["Helper Utilities (connectorUtils.js)"]
    end

    subgraph "Data Aggregation & Processing"
        canvasAggr["Data Aggregator & Canvas Controller (canvasAggr.js)"]
        footprint["Footprint Module"]
        volume["Volume Module"]
        cvd["CVD Module"]
        oi["OI Module"]
    end

    subgraph "Presentation & Rendering"
        mainjs["UI Entry Point (main.js)"]
        htmlCanvas["HTML Canvas Renderer (index.html)"]
        stylecss["Styling & Presentation (style.css)"]
    end

    subgraph "Build & Configuration"
        buildSystem["Build System (Vite & package.json)"]
    end

    wsBinance -->|"streamsData"| canvasAggr
    connectorUtils -->|"assists"| wsBinance
    canvasAggr -->|"aggregatesData"| footprint
    canvasAggr -->|"aggregatesData"| volume
    canvasAggr -->|"aggregatesData"| cvd
    canvasAggr -->|"aggregatesData"| oi
    footprint -->|"renders"| mainjs
    volume -->|"renders"| mainjs
    cvd -->|"renders"| mainjs
    oi -->|"renders"| mainjs
    mainjs -->|"initializesCanvas"| htmlCanvas
    stylecss -->|"styles"| htmlCanvas
    buildSystem -->|"bundles"| mainjs
    buildSystem -->|"serves"| htmlCanvas

    class wsBinance,connectorUtils dataSource
    class canvasAggr,footprint,volume,cvd,oi aggregation
    class mainjs,htmlCanvas,stylecss ui
    class buildSystem build

    click wsBinance "https://github.com/akenshaw/flowsurface-web/blob/suite-one/wsBinance.js"
    click connectorUtils "https://github.com/akenshaw/flowsurface-web/blob/suite-one/connectorUtils.js"
    click canvasAggr "https://github.com/akenshaw/flowsurface-web/blob/suite-one/canvasAggr.js"
    click mainjs "https://github.com/akenshaw/flowsurface-web/blob/suite-one/main.js"
    click htmlCanvas "https://github.com/akenshaw/flowsurface-web/blob/suite-one/index.html"
    click stylecss "https://github.com/akenshaw/flowsurface-web/blob/suite-one/style.css"
    click buildSystem "https://github.com/akenshaw/flowsurface-web/blob/suite-one/vite.config.js"

classDef dataSource fill:#ADD8E6,stroke:#000,stroke-width:2px;
classDef aggregation fill:#90EE90,stroke:#000,stroke-width:2px;
classDef ui fill:#FFCC99,stroke:#000,stroke-width:2px;
classDef build fill:#DDA0DD,stroke:#000,stroke-width:2px;
```
