System Architecture

Roadsign · Hyperliquid Order Terminal — Module Planning · Standalone-first · Self-hostable

ImplementedIn ProgressPlannedFull architecture spec: docs/ROADSIGN_MASTER_ARCHITECTURE.md
HL
Hyperliquid Integration Layer
Data Source · Smart Contract Execution · HyperCore
Connected
Public WebSocket (server-side, shared by all users)
  • trades feedReal-time trade push → candle aggregation source
  • candle (official intervals)Fixed-interval supplement (candleSnapshot REST history backfill)
  • allMidsAll-coin mid-price subscription
Private WebSocket (per-user, with master address)
  • clearinghouseStatePositions / margin / account value (WS real-time + HTTP fallback)
  • orderUpdatesOrder status real-time changes (WS push)
  • userFillsFill reports (WS real-time push)
  • openOrdersCurrent open orders (HTTP query)
  • userFundingsFunding rate payments
REST info endpoint · POST /info
  • meta / metaAndAssetCtxsInstrument specs / max leverage / market data
  • clearinghouseStateAccount snapshot (requires master address, 5s cache)
  • userFillsFill history query
  • webData2Advanced account data
  • recentTradesHistorical trade query (feed startup backfill)
  • predictedFundingsCross-exchange funding rate prediction
Exchange endpoint · POST /exchange (all require EIP-712 signature)
  • orderLimit GTC + market IOC orders (testnet verified)
  • cancel / cancelByCloidCancel orders (testnet verified)
  • modify / batchModifyModify orders (testnet verified)
  • updateLeverageAdjust leverage (dynamic maxLeverage)
  • twapOrder / twapCancelTWAP batch execution
  • approveAgentDynamic Agent Wallet auth + MetaMask EIP-712 signing
SC
Scale Architecture
Horizontal Node Scaling · Sticky Routing · Zero Lag
In Progress
Public Market Data Layer (shared by all users)
  • Shared HyperliquidEthFeedOne feed serves all users, no duplicate HL connections
  • Custom interval aggregation31 intervals (18 custom + 13 traditional), server-side real-time
  • Disk persistenceRaw trades NDJSON archive (candles aggregated in-memory)
  • SSE Pub/Sub Fanout1 broadcaster per (coin,interval) → N subscriber queues
  • Frontend IndexedDB cacheHistory bars cached in browser, only fetch deltas
  • Account state TTL cacheclearinghouseState 5s cache, market data 30s cache
  • Shared market data cacheMulti-node shared market state (Redis or equivalent)
Standalone Data Collector (daemon)
  • All-coin trades collectionIndependent systemd service, up to 400 concurrent WS connections
  • NDJSON disk writerPer-coin per-hour file rotation
  • Auto instrument refreshQuery new instruments every 30s and auto-subscribe
Private Account Layer (per-user isolation)
  • Account SSE streamAccountStreamBroadcaster per wallet, WS subscribe + 30s HTTP fallback
  • Session isolationFull user data isolation
  • workspaceId sticky routingSame workspaceId routes to same node
VM Horizontal Scaling (hosted version)
  • Auto scale-outAdd nodes based on concurrent load
  • Auto scale-inReduce idle resources
Self-hosting (docker-compose up)
  • Full version one-command startdocker-compose up → localhost:9120
  • Chart-only modeROADSIGN_MODE=chart-only implemented
  • config.ymlInstruments / risk limits / custom intervals all configurable
  • Environment variable configHL_API_URL / HL_AGENT_KEY / ROADSIGN_MODE etc.
Distributed Node Network (long-term)
  • Any machine can be a nodePeer-to-peer, 369pill.app has no privilege
  • P2P node discoveryNodes broadcast to each other, keeping system alive
  • Open-source strategy/indicator pluginsCommunity contributions and sharing
URL Routing Structure
  • Multi-locale page routing/roadsign/{locale}/swap/{instrument} (zh-hant / en / ja)
  • API routing/roadsign/api/v1/market/{instrument}/bars|stream
  • workspaceId#workspaceId=...&interval=...&tz=... (hash, client-side)
  • nginx sticky routingRoute by workspaceId header to target node
IE
Indicator Engine (Shared Service)
Technical Indicator Computation · Pure Function Library · Shared by Chart & Strategy
Running
Indicator Library (packages/roadsign_indicators/)
  • MA (SMA/EMA/RMA/WMA/VWMA)Five moving average types · configurable source & period
  • RSIRelative Strength Index (Wilder's smoothing)
  • MACDFast/slow lines + histogram + signal line
  • Stochastic KDStochastic oscillator %K / %D
  • OBVOn Balance Volume trend
  • ZenTrendProprietary dual-timeframe trend · confluence arrows
Frontend Rendering (main overlay + addPane sub-charts)
  • MA main overlayLineSeries on top of candlesticks
  • ZenTrend main overlayDual lines + fill + HTF stepped line + arrow markers
  • RSI / KD / MACD / OBV sub-chartsaddPane panels · reference lines · gradient fills
  • Indicator legend + search panelTag bar / live values / param editing / visibility toggle
External API
  • GET /api/v1/indicators/{coin}/{type}Single indicator value series (6 indicator types)
  • GET /api/v1/indicators/{coin}/multiBatch multiple indicators
  • pip install roadsign-indicatorspackages/ available locally, not yet on PyPI
AS
Account State Manager (Shared Service)
Account SSOT · Real-time Push · All modules read from here
Running
Data Sources (Hyperliquid API)
  • clearinghouseStatePositions / margin / account value (5s TTL cache)
  • frontendOpenOrdersCurrent open orders
  • userFillsFill report queries
  • markets()Full instrument list (perp + tradfi, 30s cache)
External API
  • GET /api/v1/account/summaryEquity / available / perp balances
  • GET /api/v1/account/positionsCurrent position list
  • GET /api/v1/account/ordersCurrent order list
  • GET /api/v1/account/fillsFill details (filterable by coin)
  • GET /api/v1/account/marketsFull instrument list (sorted by 24h volume)
  • SSE /api/v1/account/streamReal-time account push (WS subscribe + HTTP fallback)
Security Rules
  • Query via master addressConfigured via HL_MASTER_ADDRESS env var
  • Per-user session isolationFull user data isolation
EG
EffectGateway + Signing Layer (Shared Service)
Single Execution Gateway · EIP-712 Signing · Agent Wallet Nonce Management
Running
Agent Wallet Authorization Model
  • approveAgent (one-time)Dynamic Agent Wallet auth + MetaMask EIP-712 signing
  • EIP-712 per-order signingSDK sign_l1_action · testnet verified
  • Nonce managementMillisecond timestamp (SDK get_timestamp_ms)
  • Dynamic session modePer-user gateway or global default gateway
External API (single execution gateway for all modules)
  • POST /execution/orderLimit GTC + market IOC
  • POST /execution/cancelCancel orders
  • POST /execution/modifyModify orders
  • POST /execution/triggerTP/SL trigger orders
  • POST /execution/leverageAdjust leverage
  • POST /execution/trailingTrailing stop
  • POST /execution/twapTWAP batch execution
Action Whitelist (enforced security boundary)
  • Trading operationsorder / cancel / modify / batchModify / updateLeverage
  • Advanced operationsupdateIsolatedMargin / approveAgent / twapOrder / twapCancel
  • Fund operations blockedwithdraw3 / usdSend / spotSend all fund transfers blocked
01
Chart System
LightweightCharts v5 · Custom Intervals · Drawing Tools · Indicator Overlay
Running
Candlestick Chart
  • Custom interval candles31 intervals (18 custom + 13 traditional)
  • SSE real-time updatesBar push + change detection + heartbeat
  • History paginationAuto-load on scroll left + IndexedDB cache
  • Multi-coin switching310 instruments dynamic list + coin selector
  • Chart typesCandlestick / Heikin Ashi / Line
  • Chart Health auto-healAuto-detect and recover abnormal chart state
Drawing Tools (6 types · LC Line Tools Plugin)
  • HorizontalLine / HorizontalRayHorizontal line · ray · OHLC magnet snap
  • TrendLine / RayTrend line · ray · magnet alignment
  • FibRetracementFibonacci retracement (11 levels · custom coefficients)
  • PriceRangeRange annotation · % change · HTML overlay
  • Object Tree SSOTlocalStorage persistence · cross-chart sync
  • Undo / Redo50-deep undo stack
Drawing Interactions
  • Magnet snapThree modes (off / weak / strong) · OHLC snap
  • Quick ToolbarFloating toolbar on selection (color/width/lock/delete)
  • Color PickerHSV wheel + opacity + hex input + swatches
  • Right-click menu / double-click settingsUnified object interaction layer
  • Continuous draw modeAuto-start next tool after completing one
Price Line System
  • Support / Resistance / Alert lineslocalStorage persistence · LC createPriceLine
  • Alert triggerStatus changes to 'hit' when price crosses
  • Position / Order overlay linesReal-time entry price lines + order lines
02
Order System
roadsign Order Module
Running
Order Types
  • Limit orderGTC at specified price
  • Market orderIOC at best available price
  • Take Profit / Stop LossTrigger conditional orders
  • Trailing stopDynamic callback tracking · % callback · activation price
  • TWAPFrontend batch submission · custom slices / interval
Margin / Leverage
  • Cross / Isolated toggleDropdown switch · synced from position mode
  • Leverage multiplierDynamic maxLeverage + synced from current position
  • Available margin calcperp_value - total_margin_used
Order Panel UI
  • Auto price fillFollow latest trade / crosshair click to fill
  • Percentage presets25/50/75/100% · custom edit · localStorage save
  • Size unit togglecoin <-> USDC auto conversion
  • Three-mode tabsManual / Semi-auto / Full-auto
  • Fee estimateMaker 0.01% / Taker 0.035% real-time calculation
  • SSE account real-timeBalance / positions without polling
Signing Layer (Agent Wallet mode)
  • approveAgent (one-time)Dynamic Agent Wallet + MetaMask signing auth
  • EIP-712 per-order signingAgent signs, no MetaMask popup needed
  • Action WhitelistAgent blocked from withdraw / usdSend fund ops
  • Retry logicAuto retry on network error (3 attempts)
03
Orders & Positions Report
roadsign Positions & Orders Module
Running
Real-time Panel (SSE push + HTTP fallback)
  • Open ordersInstrument / side / size / price / cancel button
  • PositionsSize / avg price / mark / liq price / UPnL / close button
  • Fill detailsPer-fill / fee / realized PnL · coin filter
  • Asset summaryEquity / available / margin used / UPnL
Chart Overlay
  • Position overlayEntry price line + HTML label (size / live PnL / close btn)
  • Order overlayOrder price line + HTML label · drag-to-modify support
  • Quick actionsCancel / modify price / set TP/SL directly from chart
Position Actions
  • Close position modalMarket / limit · % slider · live PnL estimate
  • Modify order modalAdjust price / size
  • Trailing stop modalCallback % / activation price
  • TP/SL modalTake profit / stop loss · live mark price
  • Close all positionsMarket close all open positions
History
  • Fill history filterCoin filter UI
  • Historical ordersFilter by date / instrument / side
  • Funding rate historyuserFunding REST
04
Admin Dashboard
roadsign Admin Module
In Progress
Health Monitoring (/roadsign/admin)
  • System health APIGET /api/v1/admin/health · uptime / feed / memory
  • Admin dashboard pageReal-time monitoring panel · 3s auto-refresh
  • Feed healthWS connection state / latency / disconnect count
Frontend Status Bar
  • Stream health indicatorSSE connection state + latency display
  • Bar countdown timerSeconds until next bar
  • OHLC legendCrosshair / latest bar OHLCV values
Future Expansion
  • User managementAccount review / permission levels
  • API response monitoringEndpoint latency / error rates
  • Node load monitoringPer-VM CPU / memory
05
Member / Referral System
roadsign Member + Referral Module
In Progress
Wallet Connection (MetaMask)
  • MetaMask connecteth_requestAccounts + address display
  • Agent Wallet authEIP-712 signing modal + dynamic session
  • Auto reconnectRestore from localStorage on page load
  • Session persistencewallet_sessions.json disk storage
Referral System
  • Generate referral codeRS-XXXXXXXX (unique per wallet)
  • Apply referral codeNew user binds referrer (anti-self / anti-duplicate)
  • Referral statsQuery referred user count
  • Code lookupReverse lookup code ownership
Workspace Preferences
  • Timezone / interval / layoutHash params implemented (#workspaceId=...)
  • Personal PnL analyticsDaily / weekly / monthly performance
  • Win rate / PnL ratioPer-instrument distribution analysis
06
AutoTrader System
roadsign AutoTrader Module
In Progress
Signal Intake
  • REST WebhookExternal strategy signals → auto-execute orders
  • Built-in strategy engineBaseStrategy plugin interface + strategy polling loop
  • MACD DivergenceMACD histogram zero-cross strategy
  • Webhook RelayExternal signal pass-through strategy (TradingView etc.)
Risk Control (RiskGuard)
  • Max position capRiskConfig limits per-coin / total position
  • Daily loss circuit breakerAuto-stop on limit breach
  • Min / max order sizemin_order_size_usd / max_order_size_usd
  • Action safety filterFORBIDDEN_ACTIONS blocks fund transfers
API
  • POST /autotrader/startStart strategy · specify coin / interval / params
  • POST /autotrader/stopStop strategy
  • GET /autotrader/statusStrategy status (total_signals / total_orders / rejected)
  • POST /autotrader/webhookWebhook signal immediate execution
Execution Engine
  • HTTP loopbackFetches bars / indicators / submits orders via own API
  • Auto TP/SL placementStrategy signals with tp / sl auto-submit trigger orders
  • Strategy analyticsSharpe / Alpha / execution logs