Skip to content

Commit deff4e0

Browse files
sahmed0sahmed0
committed
Initial commit
0 parents  commit deff4e0

44 files changed

Lines changed: 6155 additions & 0 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/deploy.yml‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# Simple workflow for deploying static content to GitHub Pages
2+
name: Deploy static content to Pages
3+
4+
on:
5+
# Runs on pushes targeting the default branch
6+
push:
7+
branches: ["main"]
8+
9+
# Allows you to run this workflow manually from the Actions tab
10+
workflow_dispatch:
11+
12+
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
13+
permissions:
14+
contents: read
15+
pages: write
16+
id-token: write
17+
18+
# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
19+
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
20+
concurrency:
21+
group: "pages"
22+
cancel-in-progress: false
23+
24+
jobs:
25+
# Single deploy job since we're just deploying
26+
deploy:
27+
environment:
28+
name: github-pages
29+
url: ${{ steps:deployment.outputs.page_url }}
30+
runs-on: ubuntu-latest
31+
steps:
32+
- name: Checkout
33+
uses: actions/checkout@v4
34+
- name: Set up Node
35+
uses: actions/setup-node@v4
36+
with:
37+
node-version: 20
38+
cache: 'npm'
39+
- name: Install dependencies
40+
run: npm ci
41+
- name: Build
42+
run: npm run build
43+
- name: Setup Pages
44+
uses: actions/configure-pages@v5
45+
- name: Upload artifact
46+
uses: actions/upload-pages-artifact@v3
47+
with:
48+
# Upload entire repository
49+
path: './dist'
50+
- name: Deploy to GitHub Pages
51+
id: deployment
52+
uses: actions/deploy-pages@v4

‎.gitignore‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
# Logs
2+
logs
3+
*.log
4+
npm-debug.log*
5+
yarn-debug.log*
6+
yarn-error.log*
7+
pnpm-debug.log*
8+
lerna-debug.log*
9+
10+
# Dependencies
11+
node_modules
12+
dist
13+
dist-ssr
14+
*.local
15+
16+
# Editor directories and files
17+
.vscode/*
18+
!.vscode/extensions.json
19+
.idea
20+
.DS_Store
21+
*.suo
22+
*.ntvs*
23+
*.njsproj
24+
*.sln
25+
*.sw?
26+
27+
# Environment variables
28+
.env
29+
.env.local
30+
.env.development.local
31+
.env.test.local
32+
.env.production.local
33+
*.env.local
34+
35+
# TypeScript
36+
*.tsbuildinfo
37+
38+
# Build outputs
39+
build/
40+
out/
41+
.vite/
42+
43+
# Testing
44+
coverage/
45+
46+
# OS-specific files
47+
Thumbs.db
48+
ehthumbs.db
49+
Desktop.ini
50+
51+
# Secrets/Certificates
52+
*.pem
53+
*.key
54+
*.pub

‎LICENSE‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
PROPRIETARY LICENSE
2+
ALL RIGHTS RESERVED.
3+
NO PERMISSION FOR DISTRIBUTION, MODIFICATION, OR AI TRAINING.
4+
5+
Copyright (c) 2026 SAJID AHMED
6+
7+
1. OWNERSHIP AND INTENT
8+
This software, including all source code, logic, assets, documentation files, and associated data structures (collectively, the "Software" and "Database"), is the exclusive intellectual property of SAJID AHMED (the "Author").
9+
10+
The Software is made publicly available on GitHub strictly for the purposes of professional portfolio review, recruitment evaluation, and technical demonstration. It is NOT Open Source software.
11+
12+
2. LIMITED PERMISSIONS & GITHUB TERMS OF SERVICE
13+
By hosting this Software on GitHub, the Author acknowledges the mandatory rights granted under the GitHub Terms of Service for public repositories. Subject to those terms, the Author grants users a strictly limited, non-exclusive, non-transferable permission to:
14+
- View: Read the source code on the GitHub platform.
15+
- Fork: Create a "fork" of the repository strictly within the GitHub platform for personal, non-commercial review or bookmarking.
16+
- Clone/Download: Copy the Software to a local machine solely for the purpose of non-commercial execution, evaluation, and review.
17+
18+
3. RESTRICTIONS AND PROHIBITIONS
19+
Any use of the Software not explicitly granted in Section 2 is strictly prohibited. You may NOT:
20+
- Modify: Alter, change, or create derivative works from the Software for any purpose.
21+
- Redistribute: Copy, publish, host, or distribute the Software (or any portion of it) on any platform, medium, or website other than the original GitHub repository.
22+
- Commercialise: Use the Software, or any portion thereof, for any commercial purpose, financial gain, or as part of a for-profit service.
23+
- Sublicense: Sell, rent, lease, or grant any rights to third parties to use the Software.
24+
25+
4. ASSERTION OF MORAL RIGHTS & DATABASE RIGHTS
26+
In accordance with Chapter IV of the Copyright, Designs and Patents Act 1988 (CDPA), the Author explicitly asserts their Moral Rights, including the right to be identified as the author of this work (Right of Paternity) and the right to object to any derogatory treatment of the Software (Right of Integrity). The Author furthermore asserts Database Rights over any structured data, JSON files, or proprietary data schemas contained within the Software.
27+
28+
5. AI, MACHINE LEARNING, AND DATA MINING RESTRICTIONS
29+
The Author expressly withholds permission for this Software to be used for the development, training, or validation of artificial intelligence. You are strictly forbidden from:
30+
- Using the Software as training data for Machine Learning (ML) models, Large Language Models (LLMs), or any generative AI systems.
31+
- Using the Software for automated code synthesis, pattern recognition, or AI-assisted code generation.
32+
- Scraping or ingesting the Software into any database used for the commercial or non-commercial development of AI technologies.
33+
34+
THIS SECTION SERVES AS AN EXPRESS, LEGALLY BINDING OPT-OUT OF ANY "FAIR USE," "TEXT AND DATA MINING," OR SIMILAR EXCEPTIONS PROVIDED UNDER UK, EU, OR INTERNATIONAL COPYRIGHT LAWS.
35+
36+
6. CONTRIBUTIONS AND COLLABORATION
37+
To protect the unilateral ownership of this portfolio:
38+
- 6.1 No Unsolicited Contributions: The Author does not accept unsolicited contributions, Pull Requests, or collaborative edits. This is a sole-authored project.
39+
- 6.2 Implied License for Submissions: Any person who, notwithstanding Section 6.1, submits code or content to this repository ("Contributor") retains their original copyright under UK law. However, by the act of submission, the Contributor grants the Author an irrevocable, perpetual, worldwide, royalty-free, and sub-licensable license to use, display, modify, and distribute that contribution as part of this Software.
40+
- 6.3 Formal Assignment: Full legal ownership of any contribution shall only transfer to the Author via a separate, written Contributor License Agreement (CLA) or Assignment of Copyright signed by both parties in accordance with Section 90 of the CDPA 1988.
41+
- 6.4 Right of Removal: The Author reserves the absolute right to reject, modify, or delete any contribution or revoke repository access at any time.
42+
43+
7. NO WARRANTY AND LIMITATION OF LIABILITY
44+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

‎README.md‎

Lines changed: 181 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,181 @@
1+
# Heatmap: Real-Time Order Book Visualisation
2+
3+
[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue.svg)](https://www.typescriptlang.org/)
4+
[![SolidJS](https://img.shields.io/badge/SolidJS-1.9-76b5c5.svg)](https://www.solidjs.com/)
5+
[![Vite](https://img.shields.io/badge/Vite-7.x-646cff.svg)](https://vitejs.dev/)
6+
7+
A high-performance, multi-threaded financial data visualisation tool for rendering real-time order book heatmaps. This project implements a local order book engine synced with the Binance BTC/USDT spot market, providing traders with deep insights into market liquidity and volume clusters.
8+
9+
## Table of Contents
10+
11+
- [Key Features](#key-features)
12+
- [Architecture](#architecture)
13+
- [Tech Stack](#tech-stack)
14+
- [Key Technical Decisions](#key-technical-decisions)
15+
- [Challenges & Lessons](#challenges--lessons)
16+
- [Installation & Usage](#installation--usage)
17+
- [License](#license)
18+
19+
---
20+
21+
## Key Features
22+
23+
- **Multi-Threaded Pipeline:** Utilises Web Workers to decouple data ingestion (`DataWorker`) from rendering (`RenderWorker`), ensuring the main UI thread remains responsive even during high-volatility market events.
24+
- **High-Performance Binning:** Employs a zero-allocation `HeatmapProcessor` that uses pre-allocated `TypedArrays` to process thousands of order book levels into normalised heatmap slices in sub-10ms intervals.
25+
- **Rank-Based Normalisation:** Implements a rank-transform algorithm to map power-law distributed order book volumes into a 5-step discrete intensity scale (Weather Radar style) for maximum visual clarity.
26+
- **Sub-Pixel Smooth Rendering:** Features a custom "shift-and-draw" rendering engine on an `OffscreenCanvas` with float-based coverage blending for sub-pixel accuracy.
27+
- **Full Order Book Integrity:** Maintains a local order book with 5000 levels per side, featuring snapshot reconciliation and sequence gap detection to ensure 100% data accuracy relative to the exchange.
28+
- **Adaptive UI:** Includes interactive controls for zoom, pan, auto-centring, and volume filtering, alongside dynamic price and time axes.
29+
30+
---
31+
32+
## Architecture
33+
34+
The system follows a reactive, decoupled architecture where the main thread orchestrates a direct `MessageChannel` between the data and render workers.
35+
36+
### Directory Structure
37+
38+
```text
39+
src/
40+
├── components/ # Layout-level SolidJS components
41+
├── core/ # Application services (HeatmapService) and context
42+
├── engine/ # Core business logic (Binning, Normalisation, Book Core)
43+
│ ├── bookCore.ts # Order book data structures
44+
│ ├── processor.ts # Heatmap binning & rank normalisation logic
45+
│ └── palettes.ts # Colour mappings (Magma, Viridis)
46+
├── ui/ # UI components (Axes, Legend, Controls) and Hooks
47+
│ └── useHeatmapPipeline.ts # Orchestrates worker communication
48+
├── workers/ # Multi-threading logic
49+
│ ├── data.worker.ts # Binance API connector & processing
50+
│ └── render.worker.ts # OffscreenCanvas rendering engine
51+
└── index.tsx # Application entry point
52+
```
53+
54+
### System Flow
55+
56+
```mermaid
57+
graph TD
58+
subgraph "External API"
59+
B_WS[Binance WebSocket]
60+
B_REST[Binance REST API]
61+
end
62+
63+
subgraph "DataWorker (Background Thread)"
64+
BC[BinanceConnector]
65+
HP[HeatmapProcessor]
66+
Book[Local Order Book]
67+
68+
BC -- 1. Snapshot --> B_REST
69+
BC -- 2. Stream --> B_WS
70+
BC -- 3. Update --> Book
71+
Book -- 4. Raw Data --> HP
72+
HP -- 5. Processed Slice --> Port1((MessagePort))
73+
end
74+
75+
subgraph "RenderWorker (Background Thread)"
76+
Port2((MessagePort))
77+
HR[HeatmapRenderer]
78+
Canvas[OffscreenCanvas]
79+
History[Circular Buffer]
80+
81+
Port1 -- "Direct Channel (No Main Thread)" --> Port2
82+
Port2 -- 6. Receive Slice --> History
83+
History -- 7. Render --> HR
84+
HR -- 8. Draw --> Canvas
85+
end
86+
87+
subgraph "Main Thread (SolidJS UI)"
88+
Hook[useHeatmapPipeline]
89+
UI[Dashboard & Controls]
90+
Overlay[Price/Time Axes]
91+
92+
Hook -- Control Messages --> BC
93+
Hook -- Control Messages --> HR
94+
Canvas -- Frame --> UI
95+
HR -- Viewport Stats --> Hook
96+
Hook -- Update --> UI
97+
end
98+
```
99+
100+
---
101+
102+
## Tech Stack
103+
104+
| Category | Tools |
105+
| :--- | :--- |
106+
| **Framework** | SolidJS |
107+
| **Language** | TypeScript |
108+
| **Build Tool** | Vite |
109+
| **Rendering** | OffscreenCanvas (2D Context) |
110+
| **Concurrency** | Web Workers, MessageChannel |
111+
| **Data Source** | Binance API (WebSocket & REST) |
112+
113+
---
114+
115+
## Key Technical Decisions
116+
117+
| Decision | Logic & Reasoning |
118+
| :--- | :--- |
119+
| **Web Workers** | Decoupling ingestion and rendering prevents UI "jank" and ensures the application can handle the high message throughput of the crypto markets without blocking the event loop. |
120+
| **OffscreenCanvas** | Offloading the canvas rendering to a background thread allows the `RenderWorker` to maintain a consistent 60 FPS regardless of main-thread load. |
121+
| **TypedArrays** | Using `Float64Array` and `Int32Array` in the hot path minimizes heap allocations, reducing the overhead of Garbage Collection (GC) which is critical for low-latency financial apps. |
122+
| **Rank Normalisation** | Order book volumes often follow a power-law distribution. Linear scaling results in either oversaturated or invisible data. Rank-based scaling ensures consistent visual contrast. |
123+
| **Discrete Quantisation** | Mapping intensities to 5 discrete levels (Weather Radar style) simplifies visual scanning for traders, making it easier to identify significant support/resistance levels. |
124+
125+
---
126+
127+
## Challenges & Lessons
128+
129+
### Local Order Book Synchronisation
130+
Maintaining a perfectly synced local copy of the order book requires handling the sequence of a REST snapshot followed by real-time WebSocket updates. Implementing the Binance-specific reconciliation logic (tracking `U` and `u` update IDs) was a critical challenge that reinforced the importance of sequence validation and error-handling in high-frequency data streams.
131+
132+
### Memory Management in Workers
133+
Transferring large amounts of data between workers can be expensive. By using a direct `MessageChannel` between the `DataWorker` and `RenderWorker`, the main thread is bypassed entirely for the high-frequency "Render Slice" messages, significantly reducing context-switching overhead.
134+
135+
---
136+
137+
## Installation & Usage
138+
139+
### Prerequisites
140+
141+
- [Node.js](https://nodejs.org/) (v18 or higher)
142+
- [npm](https://www.npmjs.com/) or [pnpm](https://pnpm.io/)
143+
144+
### Setup
145+
146+
1. Clone the repository:
147+
```bash
148+
git clone https://github.com/your-username/heatmap.git
149+
cd heatmap
150+
```
151+
152+
2. Install dependencies:
153+
```bash
154+
npm install
155+
```
156+
157+
3. Start the development server:
158+
```bash
159+
npm run dev
160+
```
161+
162+
4. Build for production:
163+
```bash
164+
npm run build
165+
```
166+
167+
---
168+
169+
## License
170+
![Copyright](https://img.shields.io/badge/Copyright-2026_Sajid_Ahmed-brightgreen.svg)
171+
172+
Copyright (c) 2026 Sajid Ahmed. **All Rights Reserved.**
173+
174+
This repository is a **Proprietary Project**.
175+
176+
While I am a strong supporter of Open Source Software, this specific codebase represents a significant personal investment of time and effort and is therefore provided with the following restrictions:
177+
178+
* **Permitted:** Viewing, forking (within GitHub only), and local execution for evaluation and personal, non-commercial usage only.
179+
* **Prohibited:** Modification, redistribution, commercial use, and AI/LLM training.
180+
181+
For the full legal terms, please see the [LICENSE](./LICENSE) file.

‎index.html‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
<!doctype html>
2+
<html lang="en">
3+
<head>
4+
<meta charset="UTF-8" />
5+
<link rel="apple-touch-icon" sizes="180x180" href="favicon/apple-touch-icon.png?v=2">
6+
<link rel="icon" type="image/png" sizes="32x32" href="favicon/favicon-32x32.png?v=2">
7+
<link rel="icon" type="image/png" sizes="16x16" href="favicon/favicon-16x16.png?v=2">
8+
<link rel="manifest" href="favicon/site.webmanifest?v=2">
9+
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
10+
<title>Binance Order Book Depth Heatmap | Sajid Ahmed</title>
11+
</head>
12+
<body>
13+
<div id="root"></div>
14+
<script type="module" src="src/index.tsx"></script>
15+
</body>
16+
</html>

0 commit comments

Comments
 (0)