Skip to content

Docs: brand public README and correct architecture docs #71

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
silahian merged 1 commit into from
Aug 10, 2026
Merged

Docs: brand public README and correct architecture docs #71

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
106 changes: 49 additions & 57 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,28 +1,46 @@
# VisualHFT

An open-source desktop application for real-time market microstructure analysis.

[![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-0D7C66?style=flat-square)](LICENSE.txt)
[![.NET 10](https://img.shields.io/badge/.NET-10-512BD4?style=flat-square)](https://dotnet.microsoft.com/download/dotnet/10.0)
![Windows](https://img.shields.io/badge/platform-Windows-0078D4?style=flat-square)
[![Discord](https://img.shields.io/badge/community-Discord-5865F2?style=flat-square&logo=discord&logoColor=white)](https://visualhft.com/discord)
[![GitHub Discussions](https://img.shields.io/badge/community-GitHub%20Discussions-24292F?style=flat-square&logo=github)](https://github.com/visualHFT/VisualHFT/discussions)
<p align="center">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="assets/brand/visualhft-wordmark-dark.png">
<source media="(prefers-color-scheme: light)" srcset="assets/brand/visualhft-wordmark-light.png">
<img alt="VisualHFT" src="assets/brand/visualhft-wordmark-light.png" width="260">
</picture>
</p>

<p align="center">
An open-source desktop application for real-time market microstructure analysis.
</p>

<p align="center">
<a href="https://visualhft.com">Website</a> ·
<a href="docs/README.md">Documentation</a> ·
<a href="https://visualhft.com/discord">Discord</a> ·
<a href="https://github.com/visualHFT/VisualHFT/discussions">Discussions</a>
</p>

<p align="center">
<a href="LICENSE.txt"><img alt="License: Apache-2.0" src="https://img.shields.io/badge/License-Apache--2.0-0D7C66?style=flat-square"></a>
<a href="https://dotnet.microsoft.com/download/dotnet/10.0"><img alt=".NET 10" src="https://img.shields.io/badge/.NET-10-512BD4?style=flat-square"></a>
<img alt="Platform: Windows" src="https://img.shields.io/badge/platform-Windows-0078D4?style=flat-square">
<a href="https://visualhft.com/discord"><img alt="Community: Discord" src="https://img.shields.io/badge/community-Discord-5865F2?style=flat-square&logo=discord&logoColor=white"></a>
</p>

![VisualHFT dashboard showing real-time Level 2 order book, liquidity, and market microstructure analytics](docImages/visualhft-hero-L2.gif)

[Quickstart](#quickstart) · [Write a plugin](#write-a-plugin) · [Architecture](docs/architecture.md) · [Changelog](CHANGELOG.md) · [Contributing](CONTRIBUTING.md)

## What it is

VisualHFT shows live order books and trades from supported venues in one desktop application. It gives traders, quants, and researchers a direct view of depth, liquidity, order flow, and market resilience while the market is moving.
<p align="center">
<a href="#quickstart">Quickstart</a> ·
<a href="docs/architecture.md">Architecture</a> ·
<a href="#extend-visualhft">Extend</a> ·
<a href="CHANGELOG.md">Changelog</a> ·
<a href="CONTRIBUTING.md">Contributing</a>
</p>

## What you can see
## What it does

| Order book | Studies | Extensions |
| --- | --- | --- |
| Follow depth, trades, spreads, and venue conditions in one view. | Watch VPIN, LOB Imbalance, Market Resilience, and Order-to-Trade Ratio as conditions change. | Add a market connector or study for the data and measures you need. |
VisualHFT brings live order books and trades from supported venues into one desktop view. It helps traders, quants, and researchers examine depth, liquidity, order flow, and market resilience while conditions are changing.

![Full depth order-book view updating with live bid, ask, trade, and study data](docImages/LOB_fulldepth.gif)
| Live order book | Built-in study |
| --- | --- |
| ![Full depth order-book view updating with live bid, ask, trade, and study data](docImages/LOB_fulldepth.gif) | ![LOB Imbalance study visualising changes in order-book pressure](docImages/LOB_imbalances_2.gif) |

## Quickstart

Expand All @@ -41,60 +59,34 @@ Open `VisualHFT/VisualHFT.sln` in Visual Studio and build the solution. Set `Vis

Need help with setup? See [Troubleshooting](docs/troubleshooting.md) or ask in [Discord](https://visualhft.com/discord).

## Supported venues and studies
## Included in this repository

| Type | Included examples |
| Area | Included examples |
| --- | --- |
| Market data connectors | Binance, Bitfinex, Bitstamp, Coinbase, Gemini, Kraken, KuCoin, and a generic WebSocket connector |
| Built-in studies | VPIN, LOB Imbalance, Market Resilience, and Order-to-Trade Ratio |
| Extensibility | Templates for additional market connectors and market-microstructure studies |

## What it does

- Normalises live Level 2 order book and trade updates from supported connectors.
- Displays depth, trades, spreads, liquidity changes, and study outputs in one desktop view.
- Computes market microstructure metrics through included study plugins.
- Runs trigger conditions and sends alerts to the UI or REST endpoints.
- Supports additional connectors and studies without changes to the core application.
Connectors normalise live Level 2 order-book and trade updates for the dashboard and study plugins. Study outputs can also drive trigger conditions that send alerts to the user interface or configured REST endpoints.

## Screenshots
## Extend VisualHFT

<details>
<summary>Open the current dashboard views</summary>

| Depth | Limit order book |
| --- | --- |
| ![Depth view](docImages/Aspose.Words.5b849bdf-d96d-4013-ad76-8c3daba3aead.004.png) | ![Limit order book view](docImages/Aspose.Words.5b849bdf-d96d-4013-ad76-8c3daba3aead.007.png) |

</details>

## How it works

Connectors publish normalised market data to VisualHFT. The dashboard and study plugins read that data and update the live view. See the [architecture overview](docs/architecture.md) for the component map and data flow.

## Write a plugin

VisualHFT has two extension templates:
VisualHFT has templates and guides for two extension points:

- [Market connector template](SDK-MarketConnectorTemplate/) for a new market-data source.
- [Study template](SDK-StudyTemplate/) for a custom market-microstructure calculation.

Use the matching template and guide. Plugin authors should also review `RequiredLicenseLevel` before distributing a plugin.

## Roadmap
Read the [architecture overview](docs/architecture.md) before extending the application. Use the matching template and guide before distributing a plugin.

See the [project roadmap](https://visualhft.com/#roadmap) for planned work. This README describes only functionality included in the public repository today.
## Community and updates

## Changelog
Ask questions in [Discord](https://visualhft.com/discord) or [GitHub Discussions](https://github.com/visualHFT/VisualHFT/discussions). Report bugs and feature requests through [GitHub Issues](https://github.com/visualHFT/VisualHFT/issues).

See [CHANGELOG.md](CHANGELOG.md) for changes by date.
Follow [VisualHFT Connect](https://visualhft.com/connect), [LinkedIn](https://www.linkedin.com/company/visualhft/), [X](https://x.com/visualHFT), and [Substack](https://visualhft.substack.com) for research and project updates. See [CONTRIBUTING.md](CONTRIBUTING.md) to contribute code or documentation.

## Community and contributing
## Roadmap and changes

- **Questions and live discussion:** [VisualHFT Discord](https://visualhft.com/discord)
- **Ideas and project discussion:** [GitHub Discussions](https://github.com/visualHFT/VisualHFT/discussions)
- **Bugs and feature requests:** [GitHub Issues](https://github.com/visualHFT/VisualHFT/issues)
- **Research and updates:** [VisualHFT Connect](https://visualhft.com/connect)
- **Code and documentation contributions:** [CONTRIBUTING.md](CONTRIBUTING.md)
See the [project roadmap](https://visualhft.com/#roadmap) for planned work and [CHANGELOG.md](CHANGELOG.md) for dated changes. This README describes functionality included in the public repository today.

## License

Expand Down
Binary file added assets/brand/visualhft-wordmark-dark.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added assets/brand/visualhft-wordmark-light.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
80 changes: 55 additions & 25 deletions docs/architecture.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,43 +1,73 @@
# Architecture overview

VisualHFT is a Windows desktop application built around a shared market-data layer and independently loadable plugins.

```text
Market connector plugins
↓
Normalised OrderBook and Trade models
↓
Shared helper services
↓
Dashboard and study plugins
↓
Charts, metrics, triggers, and alerts
VisualHFT is a Windows desktop application that turns live venue data into a shared market-data view, analytical studies, and configurable trigger actions. This page describes the open-source repository as it runs today.

## System at a glance

```mermaid
flowchart LR
A[Venue feed] --> B[Connector plugin]
B --> C[Normalised market models]
C --> D[Shared helpers]
D --> E[Dashboard view models]
D --> F[Study plugins]
F --> G[BaseStudyModel results]
G --> H[Charts and tiles]
G --> I[Trigger engine]
I --> J[Configured UI or REST actions]
```

## Main components
## Components and dependency boundaries

### Desktop host

The `VisualHFT` project is the WPF desktop host. It owns the dashboard, plugin-management views, trigger configuration, and application startup.
The `VisualHFT` project is the WPF application. It starts the application, loads and starts plugins, hosts the dashboard, and owns trigger configuration and the trigger engine.

### Shared core
### Shared libraries

`VisualHFT.Commons` contains shared models, helpers, plugin base classes, and contracts. `VisualHFT.Commons.WPF` contains reusable WPF-specific behavior.
`VisualHFT.Commons` contains the shared market models, helper publishers, plugin contracts, and plugin base classes. It does not depend on WPF.

### Market connector plugins
`VisualHFT.Commons.WPF` contains reusable WPF support and depends on `VisualHFT.Commons`. The desktop host can use both libraries.

Connectors derive from `BasePluginDataRetriever`. They connect to a venue, map its symbols into the configured normalised form, and publish `OrderBook` and `Trade` updates with `RaiseOnDataReceived(...)`.
### Plugins

### Study plugins
Connector and study assemblies use the shared contracts. A connector derives from `BasePluginDataRetriever`. A study derives from `BasePluginStudy`. Built-in plugins are included as project references by the host so their assemblies are copied beside the application for runtime discovery.

Studies derive from `BasePluginStudy`. They subscribe to shared market data, perform their calculation away from the incoming data callback, and publish `BaseStudyModel` values with `AddCalculation(...)`.
## Market-data path

## Plugin discovery
A connector receives a venue-specific feed, maps it into VisualHFT's normalised models, and publishes updates through `RaiseOnDataReceived(...)`. Order books, trades, providers, and symbols are delivered by the corresponding shared helper.

At startup, `PluginManager.LoadPlugins()` scans the directory that contains `VisualHFT.exe` for DLLs. It loads non-abstract types that implement `IPlugin` and that meet their declared `RequiredLicenseLevel`. There is no separate plugin folder.
Dashboard view models and study plugins subscribe to the same helpers. The helper callbacks are synchronous. A subscriber must finish quickly and must not retain the mutable `OrderBook` it receives.

For a new connector or study, start with the [extension templates](extending/README.md).
## Study results and triggers

## Interactive reference
Studies decide how to process their input. A short calculation can run in a helper callback. A study that needs to keep an order-book state or do longer work can take an `OrderBookSnapshot`, queue that work, and dispose the snapshot when it is finished.

The existing [interactive architecture map](system-architecture.html) provides a visual companion to this overview.
`BasePluginStudy.AddCalculation(...)` sends a `BaseStudyModel` through the study's aggregation and result path, then raises `OnCalculated`. The plugin manager registers single-study results with the trigger engine. The dashboard consumes the same study output for live tiles and charts.

This is deliberately not a claim that every study uses a queue or snapshot. For example, the VPIN study processes its configured trade and order-book callbacks directly, while the Market Resilience study snapshots order books before queued processing.

## Plugin discovery and lifecycle

At startup, `PluginManager.LoadPlugins()` scans the directory containing `VisualHFT.exe` for DLLs. It creates non-abstract exported types that implement `IPlugin`, then starts the applicable connector, study, or multi-study lifecycle.

For a source build, add an extension project as a `ProjectReference` to `VisualHFT.csproj`. Its output must be copied next to the application executable for the runtime loader to discover it. Discovery loads assemblies in the application process. It is not a process-isolation boundary.

## Extending VisualHFT

Start from the public templates:

- [Market connector template](../SDK-MarketConnectorTemplate/MarketConnectorSDK_Guidelines.md)
- [Study template](../SDK-StudyTemplate/StudySDK_Guidelines.md)
- [Extension guide](extending/README.md)

## Source map

- [Application startup](../App.xaml.cs)
- [Plugin discovery and lifecycle](../PluginManager/PluginManager.cs)
- [Connector publish contract](../VisualHFT.Commons/PluginManager/BasePluginDataRetriever.cs)
- [Study result contract](../VisualHFT.Commons/PluginManager/BasePluginStudy.cs)
- [Order-book callback helper](../VisualHFT.Commons/Helpers/HelperOrderBook.cs)
- [Disposable order-book snapshot](../VisualHFT.Commons/Model/OrderBookSnapshot.cs)

For a visual companion, see the [interactive architecture map](system-architecture.html).
8 changes: 0 additions & 8 deletions docs/extending/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,12 +13,4 @@ Both templates compile against the current shared plugin APIs. Follow the linked

VisualHFT discovers plugin DLLs in the directory that contains `VisualHFT.exe`. For a source build, add the extension project as a `ProjectReference` in `VisualHFT.csproj`, then rebuild the solution. No manual registration is required.

## License level

`IPlugin.RequiredLicenseLevel` is checked when VisualHFT loads a plugin. The public base classes default to `eLicenseLevel.COMMUNITY`. Keep that default, or explicitly return it, for a plugin intended for this public repository.

```csharp
public override eLicenseLevel RequiredLicenseLevel => eLicenseLevel.COMMUNITY;
```

See the [architecture overview](../architecture.md) for the data flow and plugin boundary.
Loading