How flowsurface-rs/flowsurface works
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: dashboard.rs Dashboard · stream.rs Stream state · main.rs App entry · connector.rs Connector
Components 21
Desktop app
Native iced UI, screens, widgets, modals, and runtime shell.
- App entry · Starts the desktop terminal and wires the application lifecycle.
src/main.rs - Window shell · Creates and manages the native application window.
src/window.rs - Screen router · Top-level screen selection and application navigation.
src/screen.rs - Dashboard · Main multi-pane trading workstation layout.
src/screen/dashboard.rs - Pane layout · Arranges dashboard panes and their local state.
src/screen/dashboard/pane.rs - Panels · Hosts live trading panels such as ladder and time-and-sales.
src/screen/dashboard/panel.rs - Sidebar · Dashboard-side controls and workspace navigation.
src/screen/dashboard/sidebar.rs - Tickers table · Table view for symbols and live market rows.
src/screen/dashboard/tickers_table.rs - Modals · Overlay flows for layout, network, theme, audio, and pane settings.
src/modal.rs - Charts · Chart rendering and indicator composition for market data.
src/chart.rs - Connector · Bridges UI-facing fetch and stream actions into exchange connectivity.
src/connector.rs - Widgets · Reusable layout, chart, color, split, drag, and toast widgets.
src/widget.rs - Audio & notify · Sound effects and user notifications for trade-driven events.
src/audio.rs
Shared model
Domain state, aggregation, layout, config, and persistence logic.
- Layout & theme · Persistent workspace layout and styling state surfaced through modals.
data/src/layout.rs - Stream state · Normalizes incoming market updates into app state.
data/src/stream.rs - Aggregation · Builds time- and tick-based aggregates from raw events.
data/src/aggr.rs - Chart models · Shared chart and indicator data structures used by the UI.
data/src/chart.rs - Panel models · 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 · Provider-agnostic connectivity, limiting, depth, proxy, and units.
exchange/src/lib.rs - Adapters · Provider implementations for Binance, Bybit, Hyperliquid, MEXC, and OKX.
exchange/src/adapter.rs
Build & release
Packaging scripts and CI workflow automation.
- Scripts & CI · Packaging scripts and GitHub Actions for linting, formatting, and releases.
.github/workflows/release.yaml
Connections 21
- 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.