# flowsurface-rs/flowsurface architecture

> Architecture diagram of the GitHub repository flowsurface-rs/flowsurface, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/flowsurface-rs/flowsurface
- Repository: https://github.com/flowsurface-rs/flowsurface

## Overview

Flowsurface is a Rust workspace for a native desktop crypto-market terminal built on `iced`. The repository is split into three main layers: the application shell/UI in `src`, reusable domain/state logic in `data`, and exchange connectivity in `exchange`.

1. **Top-level application**
   - `src/main.rs`, `src/window.rs`, and `src/screen.rs` are the entry points for the desktop app lifecycle and window management.
   - The app is cross-platform and packaged for Windows, macOS, and Linux, with build/release scripts in `scripts/` and GitHub Actions for linting, formatting, and releases.

2. **Primary UI composition**
   - The main UI is organized around a dashboard screen: `src/screen/dashboard.rs` plus its `pane`, `panel`, `sidebar`, and `tickers_table` submodules.
   - This suggests a multi-pane trading workstation layout with a sidebar, ticker list, and several independent chart/panel regions.

3. **Modal and settings flow**
   - `src/modal/` contains overlays and configuration surfaces such as layout management, network settings, theme editor, audio settings, and per-pane settings.
   - These modals act as the control plane for persistent app state, user preferences, and workspace editing without leaving the main dashboard.

4. **Charting subsystem**
   - `src/chart/` contains the visualization layer for market data: heatmaps, comparisons, candlesticks, indicators, and time/scale logic.
   - The chart stack is not just rendering; it includes scale handling (`linear`, `timeseries`) and indicator composition for footprint-style overlays and derived studies.

5. **Dashboard panels**
   - The dashboard’s panel layer includes order-book/DOM ladder and time-and-sales views.
   - These panels are the live-trading companions to the charts, showing current depth and recent trades alongside the primary visualizations.

6. **Reusable widgets**
   - `src/widget/` holds shared UI primitives such as chart widgets, color picker, drag/reorder behavior, split layouts, toasts, and decorative helpers.
   - This indicates the application uses a modular widget architecture rather than monolithic screens, which is important for understanding layout composition and interaction boundaries.

7. **Shared domain/state crate**
   - The `data` crate appears to be the shared model and transformation layer used by the UI.
   - It contains aggregation logic (`aggr/`), chart models, panel data, streaming state, configuration, layout persistence, logging, and utility code.
   - This is likely where raw market events are normalized into chart-ready series and pane/dashboard state.

8. **Market data ingestion and aggregation**
   - The `data` crate’s stream and aggregation modules suggest a pipeline from incoming ticks/trades to derived time-based or tick-based buckets.
   - The README confirms live trade capture, historical backfill for Binance, and order-book-driven heatmap/DOM behavior, so the data layer is responsible for reconciling live and historical inputs into a consistent model.

9. **Exchange connectivity crate**
   - The `exchange` crate isolates provider-specific integration for Binance, Bybit, Hyperliquid, MEXC, and OKX.
   - It contains adapter implementations, connection management, rate limiting, proxy handling, and unit types for price/quantity, which keeps exchange-specific protocol details away from the UI and shared state.

10. **Connector boundary in the app**
    - The application-side `src/connector/` modules appear to bridge the UI/data layer to the exchange crate, handling fetching, streaming, and proxy concerns.
    - This is the main boundary where external market APIs and WebSockets enter the app before being transformed into internal state.

11. **Audio and notifications**
    - `src/audio.rs`, `src/notify.rs`, and `data/src/audio.rs` support trade-driven sound effects and user feedback.
    - The asset bundle includes sound effects and font resources, so alerts are part of the real-time market interaction model, not just cosmetic extras.

12. **Persistence and styling**
    - Theme, sidebar, layout, timezone, and proxy config live in the shared `data/src/config/` area and are surfaced through UI modals.
    - Persistent layouts and customizable themes are first-class architecture concerns, meaning workspace state survives across sessions and directly affects screen composition.

13. **External dependencies and infrastructure**
    - The app talks directly to exchange public REST APIs and WebSockets; there is no central backend service in the repo.
    - CI/release automation is handled via GitHub Actions, and the repo includes signing keys/assets for packaging workflows, but runtime architecture is fully client-side.

14. **How data flows through the system**
    - Market data enters from exchanges through the connector/exchange boundary.
    - It is normalized and aggregated in the data crate.
    - Dashboard screens, charts, tables, and panels render from that shared state.
    - User interactions flow back through modals/widgets into persistent config/layout state, which updates the rendered workspace and connector behavior.

A useful diagram should therefore center on one client application with three major zones: exchange ingestion, shared state/aggregation, and iced-based UI composition, with audio/notifications and persistence as side concerns attached to the UI/state layer.

Main entry points: [`src/screen/dashboard.rs`](https://github.com/flowsurface-rs/flowsurface/blob/main/src/screen/dashboard.rs) (Dashboard), [`data/src/stream.rs`](https://github.com/flowsurface-rs/flowsurface/blob/main/data/src/stream.rs) (Stream state), [`src/main.rs`](https://github.com/flowsurface-rs/flowsurface/blob/main/src/main.rs) (App entry), [`src/connector.rs`](https://github.com/flowsurface-rs/flowsurface/blob/main/src/connector.rs) (Connector)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Desktop app"]
  node_main["App entry<br/>binary entry<br/>[main.rs]"]
  node_window["Window shell<br/>window host<br/>[window.rs]"]
  node_screen["Screen router<br/>screen orchestration<br/>[screen.rs]"]
  node_dashboard["Dashboard<br/>primary workspace<br/>[dashboard.rs]"]
  node_dash_pane["Pane layout<br/>dashboard composition<br/>[pane.rs]"]
  node_dash_panel["Panels<br/>[panel.rs]"]
  node_dash_sidebar["Sidebar<br/>navigation panel<br/>[sidebar.rs]"]
  node_dash_tickers["Tickers table<br/>market list<br/>[tickers_table.rs]"]
  node_modals["Modals<br/>control plane<br/>[modal.rs]"]
  node_chart_ui["Charts<br/>visualization layer<br/>[chart.rs]"]
  node_connector["Connector<br/>ingest bridge<br/>[connector.rs]"]
  node_widgets["Widgets<br/>ui primitives<br/>[widget.rs]"]
  node_audio_notify(("Audio & notify<br/>feedback<br/>[audio.rs]"))
end

subgraph group_data["Shared model"]
  node_layout_cfg["Layout & theme<br/>workspace prefs<br/>[layout.rs]"]
  node_stream["Stream state<br/>market pipeline<br/>[stream.rs]"]
  node_aggr["Aggregation<br/>market transforms<br/>[aggr.rs]"]
  node_data_chart["Chart models<br/>market models<br/>[chart.rs]"]
  node_data_panels["Panel models<br/>panel state<br/>[panel.rs]"]
end

subgraph group_exchange["Exchange layer"]
  node_exchange_core["Exchange core<br/>provider runtime<br/>[lib.rs]"]
  node_adapters["Adapters<br/>[adapter.rs]"]
end

subgraph group_infra["Build & release"]
  node_infra["Scripts & CI<br/>release automation<br/>[release.yaml]"]
end

node_main -->|"creates"| node_window
node_main -->|"runs"| node_screen
node_screen -->|"shows"| node_dashboard
node_dashboard -->|"composes"| node_dash_pane
node_dashboard -->|"composes"| node_dash_panel
node_dashboard -->|"composes"| node_dash_sidebar
node_dashboard -->|"composes"| node_dash_tickers
node_dashboard -->|"renders"| node_chart_ui
node_dashboard -->|"opens"| node_modals
node_dashboard -->|"uses"| node_widgets
node_modals -->|"edits"| node_layout_cfg
node_connector -->|"bridges"| node_exchange_core
node_connector -->|"feeds"| node_stream
node_stream -->|"normalizes"| node_aggr
node_aggr -->|"produces"| node_data_chart
node_stream -->|"updates"| node_data_panels
node_chart_ui -->|"reads"| node_data_chart
node_dash_panel -->|"reads"| node_data_panels
node_audio_notify -.->|"reacts to"| node_stream
node_adapters -->|"implements"| node_exchange_core
node_infra -.->|"builds"| node_main

click node_main "https://github.com/flowsurface-rs/flowsurface/blob/main/src/main.rs"
click node_window "https://github.com/flowsurface-rs/flowsurface/blob/main/src/window.rs"
click node_screen "https://github.com/flowsurface-rs/flowsurface/blob/main/src/screen.rs"
click node_dashboard "https://github.com/flowsurface-rs/flowsurface/blob/main/src/screen/dashboard.rs"
click node_dash_pane "https://github.com/flowsurface-rs/flowsurface/blob/main/src/screen/dashboard/pane.rs"
click node_dash_panel "https://github.com/flowsurface-rs/flowsurface/blob/main/src/screen/dashboard/panel.rs"
click node_dash_sidebar "https://github.com/flowsurface-rs/flowsurface/blob/main/src/screen/dashboard/sidebar.rs"
click node_dash_tickers "https://github.com/flowsurface-rs/flowsurface/blob/main/src/screen/dashboard/tickers_table.rs"
click node_modals "https://github.com/flowsurface-rs/flowsurface/blob/main/src/modal.rs"
click node_chart_ui "https://github.com/flowsurface-rs/flowsurface/blob/main/src/chart.rs"
click node_connector "https://github.com/flowsurface-rs/flowsurface/blob/main/src/connector.rs"
click node_widgets "https://github.com/flowsurface-rs/flowsurface/blob/main/src/widget.rs"
click node_audio_notify "https://github.com/flowsurface-rs/flowsurface/blob/main/src/audio.rs"
click node_layout_cfg "https://github.com/flowsurface-rs/flowsurface/blob/main/data/src/layout.rs"
click node_stream "https://github.com/flowsurface-rs/flowsurface/blob/main/data/src/stream.rs"
click node_aggr "https://github.com/flowsurface-rs/flowsurface/blob/main/data/src/aggr.rs"
click node_data_chart "https://github.com/flowsurface-rs/flowsurface/blob/main/data/src/chart.rs"
click node_data_panels "https://github.com/flowsurface-rs/flowsurface/blob/main/data/src/panel.rs"
click node_exchange_core "https://github.com/flowsurface-rs/flowsurface/blob/main/exchange/src/lib.rs"
click node_adapters "https://github.com/flowsurface-rs/flowsurface/blob/main/exchange/src/adapter.rs"
click node_infra "https://github.com/flowsurface-rs/flowsurface/blob/main/.github/workflows/release.yaml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_window,node_screen,node_dashboard,node_dash_pane,node_dash_panel,node_dash_sidebar,node_dash_tickers,node_modals,node_chart_ui,node_connector,node_widgets,node_audio_notify toneBlue
class node_layout_cfg,node_stream,node_aggr,node_data_chart,node_data_panels toneAmber
class node_exchange_core,node_adapters toneMint
class node_infra toneRose
```

## Components

### Desktop app

Native iced UI, screens, widgets, modals, and runtime shell.

- [App entry](https://github.com/flowsurface-rs/flowsurface/blob/main/src/main.rs): binary entry · Starts the desktop terminal and wires the application lifecycle. · `src/main.rs`
- [Window shell](https://github.com/flowsurface-rs/flowsurface/blob/main/src/window.rs): window host · Creates and manages the native application window. · `src/window.rs`
- [Screen router](https://github.com/flowsurface-rs/flowsurface/blob/main/src/screen.rs): screen orchestration · Top-level screen selection and application navigation. · `src/screen.rs`
- [Dashboard](https://github.com/flowsurface-rs/flowsurface/blob/main/src/screen/dashboard.rs): primary workspace · Main multi-pane trading workstation layout. · `src/screen/dashboard.rs`
- [Pane layout](https://github.com/flowsurface-rs/flowsurface/blob/main/src/screen/dashboard/pane.rs): dashboard composition · Arranges dashboard panes and their local state. · `src/screen/dashboard/pane.rs`
- [Panels](https://github.com/flowsurface-rs/flowsurface/blob/main/src/screen/dashboard/panel.rs): market panels · Hosts live trading panels such as ladder and time-and-sales. · `src/screen/dashboard/panel.rs`
- [Sidebar](https://github.com/flowsurface-rs/flowsurface/blob/main/src/screen/dashboard/sidebar.rs): navigation panel · Dashboard-side controls and workspace navigation. · `src/screen/dashboard/sidebar.rs`
- [Tickers table](https://github.com/flowsurface-rs/flowsurface/blob/main/src/screen/dashboard/tickers_table.rs): market list · Table view for symbols and live market rows. · `src/screen/dashboard/tickers_table.rs`
- [Modals](https://github.com/flowsurface-rs/flowsurface/blob/main/src/modal.rs): control plane · Overlay flows for layout, network, theme, audio, and pane settings. · `src/modal.rs`
- [Charts](https://github.com/flowsurface-rs/flowsurface/blob/main/src/chart.rs): visualization layer · Chart rendering and indicator composition for market data. · `src/chart.rs`
- [Connector](https://github.com/flowsurface-rs/flowsurface/blob/main/src/connector.rs): ingest bridge · Bridges UI-facing fetch and stream actions into exchange connectivity. · `src/connector.rs`
- [Widgets](https://github.com/flowsurface-rs/flowsurface/blob/main/src/widget.rs): ui primitives · Reusable layout, chart, color, split, drag, and toast widgets. · `src/widget.rs`
- [Audio & notify](https://github.com/flowsurface-rs/flowsurface/blob/main/src/audio.rs): feedback · Sound effects and user notifications for trade-driven events. · `src/audio.rs`

### Shared model

Domain state, aggregation, layout, config, and persistence logic.

- [Layout & theme](https://github.com/flowsurface-rs/flowsurface/blob/main/data/src/layout.rs): workspace prefs · Persistent workspace layout and styling state surfaced through modals. · `data/src/layout.rs`
- [Stream state](https://github.com/flowsurface-rs/flowsurface/blob/main/data/src/stream.rs): market pipeline · Normalizes incoming market updates into app state. · `data/src/stream.rs`
- [Aggregation](https://github.com/flowsurface-rs/flowsurface/blob/main/data/src/aggr.rs): market transforms · Builds time- and tick-based aggregates from raw events. · `data/src/aggr.rs`
- [Chart models](https://github.com/flowsurface-rs/flowsurface/blob/main/data/src/chart.rs): market models · Shared chart and indicator data structures used by the UI. · `data/src/chart.rs`
- [Panel models](https://github.com/flowsurface-rs/flowsurface/blob/main/data/src/panel.rs): panel state · Shared state for ladder and time-and-sales views. · `data/src/panel.rs`

### Exchange layer

Provider adapters and connectivity primitives for market access.

- [Exchange core](https://github.com/flowsurface-rs/flowsurface/blob/main/exchange/src/lib.rs): provider runtime · Provider-agnostic connectivity, limiting, depth, proxy, and units. · `exchange/src/lib.rs`
- [Adapters](https://github.com/flowsurface-rs/flowsurface/blob/main/exchange/src/adapter.rs): exchange adapters · Provider implementations for Binance, Bybit, Hyperliquid, MEXC, and OKX. · `exchange/src/adapter.rs`

### Build & release

Packaging scripts and CI workflow automation.

- [Scripts & CI](https://github.com/flowsurface-rs/flowsurface/blob/main/.github/workflows/release.yaml): release automation · Packaging scripts and GitHub Actions for linting, formatting, and releases. · `.github/workflows/release.yaml`

## Connections

- App entry → Window shell: creates · Application entry initializes the native window.
- App entry → Screen router: runs · Entry point hands control to the screen router.
- Screen router → Dashboard: shows · Primary route is the trading dashboard.
- Dashboard → Pane layout: composes · Dashboard is assembled from pane regions.
- Dashboard → Panels: composes · Dashboard includes live market panels.
- Dashboard → Sidebar: composes · Sidebar participates in workspace navigation.
- Dashboard → Tickers table: composes · Ticker table is part of the main workspace.
- Dashboard → Charts: renders · Dashboard drives chart visualizations.
- Dashboard → Modals: opens · Workspace editing and settings are handled in modals.
- Dashboard → Widgets: uses · Shared widgets provide layout and interaction primitives.
- Modals → Layout & theme: edits · Modals persist layout, theme, and other preferences.
- Connector → Exchange core: bridges · Connector hands off network work to exchange connectivity.
- Connector → Stream state: feeds · Fetched and streamed data enters the shared stream state.
- Stream state → Aggregation: normalizes · Raw events are aggregated into derived market series.
- Aggregation → Chart models: produces · Aggregates feed chart-ready models and studies.
- Stream state → Panel models: updates · Live state powers ladder and time-and-sales views.
- Charts → Chart models: reads · Charts consume shared chart models and indicators.
- Panels → Panel models: reads · Panel views render from shared panel state.
- Audio & notify → Stream state: reacts to · Notifications are triggered by market and trade events.
- Adapters → Exchange core: implements · Provider-specific adapters sit under the exchange core.
- Scripts & CI → App entry: builds · CI and packaging scripts produce desktop releases.
