// TRADERVIEW — TRADERVUE-STYLE TRADING JOURNAL

End-user walkthrough

If you're trying TraderView for the first time, jump into the 18-step tutorial — first launch through every major view, the 1425-tile Cmd-K launcher, broker imports, FIFO trade roll-up, journal + AI post-mortem, the 17-cut report engine, live halt / catalyst / scanner streams, stryke-JIT backtests, custom indicators, strategy alerts, Schedule D / C tax exports, and the community surface. Each step is self-contained and references the route handlers in crates/traderview-web/src/routes/ and the view modules in frontend/js/ by path.

Open tutorial →

Quickstart

Clone the repo, vendor uPlot, then pick a deploy target:

# 1. clone + vendor uPlot
git clone https://github.com/MenkeTechnologies/traderview
cd traderview
./scripts/vendor-uplot.sh

# 2a. desktop — Tauri v2, embedded Postgres
cargo tauri dev          # first launch downloads PostgreSQL (~80 MB)

# 2b. web — axum, external Postgres
docker compose up -d postgres
export DATABASE_URL=postgres://traderview:traderview@localhost:5432/traderview
export TRADERVIEW_JWT_SECRET=$(openssl rand -hex 32)
cargo run -p traderview-web --bin server
# open http://localhost:8080

The desktop app is a single user, fully offline. The web binary is multi-user with registration and JWT bearer auth. Same schema, same migrations, same FIFO roll-up, same frontend, same API surface.

Architecture — One Workspace, Two Deploy Targets

The desktop and web binaries are thin shells. All domain logic, all SQL, all broker parsing lives in the three library crates. The decision "embedded vs external Postgres" and "local auto-user vs multi-user with auth" is the only thing that distinguishes them.

Crate Graph

Schema — 125 Tables, 110 Migrations

Migrations under migrations/0001_initial.sql through 0110_asset_class_crypto.sql — each one adds a self-contained feature. Money is NUMERIC(20, 8) everywhere. 125 base tables, 179 indexes, 25 PostgreSQL enum types. Grouped by domain:

Enum types (25): sides (side_t, trade_side_t), statuses (trade_status_t, order_status_t, review_status_t), asset classes, alert triggers, sentiment sources, halt reason codes, etc. — see migrations/0001_initial.sql and feature-incremental migrations for the full set.

HTTP API — 3,095 Routes Under /api/

180 route files in crates/traderview-web/src/routes/. Bearer-auth required on everything except /health, /config, /auth/*, and /client-errors. WebSocket endpoints expose live feeds. Grouped by domain (representative endpoints — see frontend/js/api.js for the full method-bound bindings):

Desktop mode binds to a random localhost port and auto-logs in as the local user. Web mode requires POST /api/auth/login → JWT → Authorization: Bearer …. A custom request/response logging middleware records every request with elapsed_ms; 4xx/5xx responses get a 4KB body snippet attached to the log entry for offline debugging.

Frontend — Vanilla JS + uPlot, 1424 Views, 1425-Tile Launcher

Zero npm. Zero bundler. Zero JS framework. 299,955 LOC vanilla ES modules + 7,334 LOC CSS served as static files. axum's tower-http fs middleware in web mode; Tauri loads from disk via custom tauri://localhost scheme in desktop mode.

The launcher (Cmd+K) is the entry point — 1425 tiles across 10 categories with a live-filter search and Enter-jumps-to-first-match. There is no fixed nav strip; the topbar carries 11 shortcuts and the rest is the launcher.

Race-safe view dispatch. app.js maintains a per-dispatch token (currentViewToken()) bumped on every navigation. Every view captures the token at render start and bails after each await if the token is stale — prevents the "document.getElementById(...) returns null after navigation" crash that hits naïve SPAs when slow async resolves into a replaced DOM.

js/api.js wraps fetch with auth, error reporting, JSON parsing, and an ApiError class. js/error_reporter.js funnels window.onerror, unhandledrejection, and overridden console.error to POST /api/client-errors, queue-capped at 200 to survive a console-error loop. uPlot vendored under frontend/lib/ — pinned, reproducible, no CDN at runtime.

Importing — 13 Brokers + Column-Mapping Wizard

Built-in parsers (crates/traderview-import/src/brokers.rs):

• Webull · Lightspeed · IBKR Flex · ThinkOrSwim · TD Ameritrade · Schwab · Fidelity · ETrade · Robinhood · TradeStation · DAS Trader · TradeZero · Tradervue · Generic (column-mapping wizard)

Pipeline per upload:

1. Raw rows + file hash recorded in imports for audit / re-parse.
2. Each row maps to an execution and inserts under (account_id, broker_order_id, executed_at, symbol, side, qty, price) — dedupe-safe.
3. FIFO roll-up re-runs for affected (account_id, symbol) pairs and rewrites trades.

Re-importing the same CSV is idempotent. Unknown brokers go through the CSV Wizard — you point at any CSV, the UI maps columns to execution fields (symbol / side / qty / price / executed_at / fees), and the mapping is saved per-broker per-user. Asset class is auto-detected from symbol patterns (options: SYMyyMMddCNNNN; futures: =F suffix; FX: =X suffix).

Live Data Streams — Polled Upstream, Pushed Downstream

Server-side pollers run on tokio tasks, push to in-process DashMap+broadcast stores, then fan out to browsers over WebSocket. All stores are bounded with oldest-first eviction (halts cap 2,000; catalysts cap 10,000) so multi-day sessions don't grow without limit.

Ticker extraction (catalyst NER) handles $SYM cashtags, parenthetical (SYM) with stop-word filter, and exchange-prefixed forms (NYSE:, NASDAQ:, AMEX:, OTC:). Halt reason codes (T1, T5, LUDP, MWC1/2/3, H10, …) are looked up in a static reason-code table for readable labels.

Live WebSocket Feeds — Full Catalog (15 Endpoints)

Beyond the four foundational push feeds (halts / catalysts / ticks / Webull), the server mounts 15 WebSocket endpoints total under /ws/ in crates/traderview-web/src/routes/. Each pairs a server-side poller / scanner with a browser-side live view tile. The endpoint, its backing route file, and the scanner condition each one streams:

Algo Trading — End-to-End Strategy Engine

Full algorithmic trading subsystem: 21 strategies, 5 real brokers with native bracket orders, backtester, parameter optimizer, risk circuit breakers, and a live event stream. Built around the Strategy trait in traderview-core so the same code path runs in backtests and live.

Strategy Trait + Registry

Every strategy implements traderview_core::algo_strategies::Strategy:

pub trait Strategy: Send + Sync {
    fn kind(&self) -> StrategyKind;
    fn min_bars(&self) -> usize;
    fn evaluate_entry(&self, bars: &[PriceBar], side_mode: SideMode) -> Option<EntrySignal>;
    fn evaluate_exit(&self, bars: &[PriceBar], side: Side,
                     anchor_high: f64, anchor_low: f64) -> Option<ExitSignal>;
    // Multi-symbol strategies (pairs/stat-arb) override these:
    fn required_symbols(&self) -> Option<Vec<String>> { None }
    fn evaluate_entry_multi(&self, bars_by_symbol: &HashMap<String, Vec<PriceBar>>,
                            side_mode: SideMode) -> Option<EntrySignal> { None }
}

21 shipping strategies, each picked via strategy_type column on algo_strategies:

Broker Adapters — 5 Real REST + WS Fill Pumps

Adapter trait BrokerSink in algo_engine.rs; dispatcher picks the impl from accounts.broker at submit time. Every adapter is wiremock-tested at the contract level (38 broker tests total).

OAuth + cookie-jar handling, refresh-token rotation, auto-retry on 401, broker-specific JSON shape (hyphenated Tastytrade, camel-case Schwab, conid for IBKR) — all isolated inside the adapter; BrokerSink::submit_bracket presents one uniform interface to the engine.

Risk Circuit Breakers

Three opt-in gates in algo_strategies.risk_gates JSON. Each gate auto-trips the kill switch (sets enabled=false, kill_switch=true, appends an audit row) and webhook-fires every enabled Discord/Slack hook the user has configured. Test coverage: engine_trips_on_daily_loss_cap, engine_trips_on_consecutive_losses_cap, engine_refuses_when_position_size_cap_breached.

{
  "max_concurrent_positions": 5,
  "max_daily_loss_usd":       500.0,   // SUM(algo_runs.pnl_realized today) ≤ −cap
  "max_consecutive_losses":   4,       // walk algo_runs newest-first
  "max_position_size_usd":    10000.0  // entry_price × qty cap
}

Backtester + Parameter Optimizer

traderview_core::algo_backtest walks historical bars through the same Strategy trait the live engine uses. Pessimistic intra-bar fill model (SL wins ties when a bar's range covers both stop and TP). Returns trades, equity curve, summary stats (Sharpe, profit factor, max DD, avg R, exit-reason histogram). Covered by 9 unit tests pinning SL/TP/EOD resolution + short-side mirroring.

traderview_core::algo_optimize takes a parameter grid {key: [v1, v2, …]}, expands the Cartesian product (hard cap 1024 combinations), runs the backtester for each combo, ranks by user-chosen metric (Sharpe / TotalReturn / ProfitFactor / AvgR / ReturnMinusDd). Frontend ships curated default grids per strategy_type — sane sweep on every strategy without writing JSON.

Live Engine Flow (per bar boundary)

1. algo_runner::tick wakes on the 10s clock boundary (covers both sec10 and min1 strategies).
2. list_active_strategies: enabled=TRUE AND kill_switch=FALSE AND deleted_at IS NULL.
3. For each strategy: emit Heartbeat event with subscribed-symbol count + next-eval countdown so the frontend stdout pane shows proof-of-life every 10s.
4. If is_boundary(now, interval) false, continue. Otherwise resolve symbol_universe: watchlist_id ⇒ watchlist symbols; autoscan ⇒ top-N from the 24k US-equity symbols catalog ranked by historical volume.
5. Side-effect: LiveTickStore::ensure_subscribed(symbols) registers every pick with the Alpaca/Polygon/Finnhub WS so 10s bars start writing to price_bars within seconds.
6. For each symbol, fetch_recent_bars tries the strategy's interval directly; if empty (typical for newly-subscribed symbols), pulls 6×/30×/90× as many 10s bars and aggregates on the fly via rollup_s10 so the strategy sees its first M1 bar within ~60s.
7. Risk gates check (daily loss, consec losses, position-size cap). On breach: trip kill switch, fan-out webhooks, abort.
8. BrokerSink::submit_bracket(intent) on the dispatcher-selected sink. Native bracket on 4/5 brokers ships entry + TP + SL in a single atomic submit.
9. Fill arrives async via the broker WS pump → algo_engine::record_fill → executions + trades::rollup_account. Same pipeline every dashboard / R-distribution / equity curve already reads.

Live Event Stream — /api/ws

Engine events fan out through the realtime hub with snake_case type tags. Frontend stdout pane in the algo view subscribes to all six:

UI Surfaces — Algo View

• New strategy modal — picks strategy_type (21 options), broker_mode (internal_sim / paper / live with 30-day paper-lock), bound account, watchlist or autoscan, side_mode, sizing JSON, risk_gates JSON.
• Stdout pane — multi-pane: one per strategy + global firehose. Renders HB / SKIP / EVAL / SIGNAL / ORDER / FILL lines with throttling so chatty events don't drown the rare important ones.
• Backtest modal — symbol, interval, days back, equity, fees, slippage. Renders summary stats + last-30 trades color-coded. History panel below auto-refreshes after each run.
• Optimize modal — grid JSON (pre-populated by strategy_type), metric picker, top-N. Result table has per-row "apply" button that PUTs the winning entry_rules back to the strategy.
• Metrics modal — runs / bars / signals / orders / fills counters, total realized P&L, SVG sparkline equity curve, recent 25 orders.
• Kill switch — manual engage/release with reason text; webhook fan-out on every transition.

Resilience & Hardening

• Stale-lock recovery. Embedded Postgres checks postmaster.pid before start; if the recorded PID is dead, removes the lockfile so a SIGKILL'd parent doesn't permanently block the next launch.
• Persisted PG password. Random password file (mode 0600) in the data dir — initialized once, reused forever — so auth survives across launches.
• Backend held across axum::serve. The Embedded handle is owned by the worker thread for the lifetime of the server; explicit drop after serve. Earlier, the handle dropped at function exit and pg_ctl stop killed Postgres mid-request — every subsequent query timed out with "pool timed out".
• Real concurrency for multi-symbol fan-outs. premarket::snapshot + markets::snapshot + market_data::quotes + compare::compare all use futures_util::future::join_all — previously serial loops blocked /api/premarket/snapshot for 150 seconds and starved the pool.
• Pool sized for cold-start fan-out. max_connections=32, min_connections=4 (kept warm), acquire_timeout=15s.
• Per-view race tokens. Frontend dispatch increments a counter on every navigation; views bail post-await if their captured token is stale, preventing null-DOM crashes.
• Browser-side error sink. window.onerror, unhandledrejection, and overridden console.error all POST to /api/client-errors (queue-capped). The Rust log mirrors every browser failure.
• WebKit SecurityError guards. Under Tauri's tauri://localhost custom scheme, navigator.sendBeacon, Notification.requestPermission, new Notification, speechSynthesis.speak, and localStorage all throw cross-origin SecurityErrors. Each is try/caught so boot survives.
• CSP allows ws://127.0.0.1:* so WebSocket connections to the dynamic backend port aren't blocked under custom scheme.

Configuration

The desktop app stores its Postgres cluster under the OS-appropriate app-data directory: ~/Library/Application Support/com.menketechnologies.traderview/pg/ on macOS, ~/.local/share/com.menketechnologies.traderview/pg/ on Linux, %APPDATA%\com.menketechnologies.traderview\pg\ on Windows.

What's Built

What This Replaces

Built by MenkeTechnologies, part of the MenkeTechnologiesMeta stack alongside strykelang, zshrs, zpwr, and the broader Rust + CLI family.