Vela, our next-generation charting platform, is live at vela.luxalgo.com.
LuxAlgo
Modules

Journal

Enable the Trading Journal module, import historical executions, persist journal data to your backend, and embed journal widgets on custom pages.

View as Markdown

The Journal module (@luxalgo/vela-pro-journal) records trade executions and computes performance analytics, equity curves, and trade reviews. It requires the Trading module and is skipped if Trading is not installed. When both modules are registered, broker fills are recorded into the journal automatically as they occur, and round-trip trades and statistics are derived from those fills.

Key features include:

  • A compact side panel displaying an account selector, date-range filter (today, 7d, 30d, 365d, ytd, all), net PnL with an inline equity curve, win rate, profit factor, drawdown, recent trades, and session notes.
  • A full-screen analytics view covering the chart column with period-over-period KPIs, daily PnL, drawdown charts, a monthly performance calendar, risk and behavioral metrics, dimensional breakdowns, a searchable trades table, daily notes, and side-by-side account or period comparisons.
  • Trade and day review workflows to correct or exclude individual fills, rate setups, attach tags and mistake labels, and record planned stop-loss and profit-target levels.
  • Manual trade logging via Add trade for recording executions placed outside the workspace.

Configuration

See Installation for adding @luxalgo/vela-pro-journal to your project, then pass journal() alongside trading() in the plugins array of enableVelaPro():

import { VelaWorkspace } from '@luxalgo/vela/workspace';
import { BinanceProvider } from '@luxalgo/vela/providers/binance';
import { enableVelaPro } from '@luxalgo/vela-pro';
import { journal } from '@luxalgo/vela-pro-journal';
import { trading } from '@luxalgo/vela-pro-trading';

enableVelaPro({
    plugins: [trading(), journal({ timeZone: 'America/New_York' })],
});

const workspace = new VelaWorkspace('#chart', {
    layout: false,
    symbol: 'BTCUSDT',
    live: true,
    providers: { binance: () => new BinanceProvider() },
    persist: true,
});

Array order in plugins does not matter because Vela Pro guarantees that trading installs before journal.

Options

OptionDefaultDescription
storenew LocalJournalStore()JournalStore adapter used to persist journal data. Defaults to localStorage under the key vela-pro.journal.
timeZoneBrowser time zoneIANA time zone identifier used to bucket executions into calendar days.
syncTradingtrueAutomatically records fills emitted by the Trading module's Broker.
width400Initial side panel width in pixels. Users can resize the panel between 300 and 720 pixels.
order4Sort order among side rail panel buttons.

Trade reconstruction

The journal stores raw JournalFill records rather than precomputed trades. Closed and open round-trip trades, daily calendar totals, and performance statistics are derived from fills and recomputed automatically whenever fills are added, edited, or excluded. User-authored review metadata (trade notes, tags, mistakes, star ratings, planned stop/target levels, and daily notes) is stored separately by trade key so annotations persist across rebuilds.

During reconstruction, fills are grouped by account and symbol and processed chronologically. Same-side fills scale into the open position, opposite-side fills close exposure, and an opposite-side fill exceeding current size closes the active trade and opens a new trade in the reverse direction. Lot matching follows each account's profitMethod: 'fifo' (default), 'lifo', or 'wavg' (weighted average cost).

Each journal account has a kind indicating how its executions are populated:

KindBehavior
'sync'Mirrors the active Broker from the Trading module. Created automatically when the first fill arrives and named after broker.info.name.
'import'Populated programmatically by application code via addFills.
'manual'Populated manually by the user via Add trade (default kind when calling addAccount).

When syncTrading: true is active, broker executions are deduplicated by fill.id. Custom adapters built via Broker integration must assign stable, non-changing IDs to every Fill.

Controller API

journalController() returns the JournalController instance once enableVelaPro() installs the module, or null beforehand. A common integration pattern is importing historical executions from external broker statements or APIs:

import { journalController } from '@luxalgo/vela-pro-journal';

const journal = journalController();
if (journal) {
    await journal.ready(); // wait for JournalStore.load() to finish

    const account =
        journal.accounts().find((a) => a.broker === 'Broker X') ??
        journal.addAccount({ name: 'Broker X', broker: 'Broker X', kind: 'import', currency: 'USD', initialBalance: 10_000 });

    const { inserted, duplicates } = journal.addFills(account.id, [
        { id: 'x-1001', symbol: 'AAPL', side: 'buy', quantity: 10, price: 190.5, fee: 1, executedAt: Date.parse('2026-11-02T14:31:00Z') },
        { id: 'x-1002', symbol: 'AAPL', side: 'sell', quantity: 10, price: 193.2, fee: 1, executedAt: Date.parse('2026-11-03T15:02:00Z') },
    ]);
    console.info(`${inserted} fills imported, ${duplicates} already there`);

    journal.setRange('ytd');
    for (const trade of journal.trades()) console.info(trade.symbol, trade.direction, trade.netPnl);
}

Assign each imported fill a deterministic id such as your venue's execution ID. addFills skips any fill whose id already exists on the account and reports the count in duplicates, making repeated imports idempotent.

Additional controller methods manage accounts, fills, annotations, and filters:

MemberDescription
trades(range?), allTrades(), trade(key)Returns reconstructed trades in the active range, all trades on the selected account, or a single trade by key.
selectAccount(id), setRange(range), setCustomRange(from, to)Selects the active account or date filter ('today', '7d', '30d', '365d', 'ytd', 'all', or YYYY-MM-DD bounds).
addAccount, updateAccount, removeAccountCreates, updates, or deletes journal accounts.
addFills, updateFill, removeFill, restoreFillInserts, edits, excludes, or restores fills. Imported and synchronized fills are soft-excluded rather than permanently deleted.
annotate(tradeKey, patch)Updates a trade's notes, tags, mistakes, rating, stopLoss, or profitTarget.
addNote(body, date?), editNote, deleteNoteCreates, edits, or removes daily journal notes.
syncBroker(broker)Subscribes to fills from a Broker instance and returns an unsubscribe function.
onChange(listener)Subscribes to 'data' or 'selection' updates.

@luxalgo/vela-pro-journal also exports pure calculation helpers (computeMetrics, dayStats, equityCurve, breakdown, and related functions) that accept reconstructed trade arrays returned by the controller.

JournalStore port

Implement JournalStore to persist journal accounts, executions, annotations, and notes on your backend.

interface JournalStore {
    load(): Promise<JournalData | null>;
    save(data: JournalData): Promise<void>;
}

interface JournalData {
    accounts: JournalAccount[];
    fills: JournalFill[];
    /** User review metadata keyed by reconstructed trade key. */
    annotations: Record<string, TradeAnnotation>;
    notes: JournalNote[];
}

interface JournalAccount {
    id: string;
    name: string;
    broker: string;
    kind: 'manual' | 'import' | 'sync';
    currency: string;
    initialBalance: number | null; // enables percentage drawdown metrics when set
    profitMethod: 'fifo' | 'lifo' | 'wavg';
    createdAt: number;
}

interface JournalFill {
    id: string;
    accountId: string;
    symbol: string;
    source: 'manual' | 'import' | 'sync';
    side: 'buy' | 'sell';
    quantity: number;
    price: number;
    fee: number;
    executedAt: number; // epoch ms
    reported?: FillValues | null; // original broker/import values preserved when edited by the user
    excluded?: boolean; // soft-hidden from trade reconstruction
}

Resolve null from load() when the user has no saved journal data yet. save(data) is debounced and receives the complete JournalData document after mutations; reconstructed trades are omitted from storage and rebuilt on load.

import { enableVelaPro } from '@luxalgo/vela-pro';
import { journal, type JournalData, type JournalStore } from '@luxalgo/vela-pro-journal';
import { trading } from '@luxalgo/vela-pro-trading';

let loaded = false;

const store: JournalStore = {
    async load() {
        const res = await fetch('/api/journal', { credentials: 'include' });
        if (!res.ok && res.status !== 404) throw new Error(`Journal: HTTP ${res.status}`);
        loaded = true;
        return res.status === 404 ? null : ((await res.json()) as JournalData);
    },
    async save(data) {
        if (!loaded) return;
        await fetch('/api/journal', {
            method: 'PUT',
            credentials: 'include',
            headers: { 'content-type': 'application/json' },
            body: JSON.stringify(data),
        });
    },
};

enableVelaPro({ plugins: [trading(), journal({ store })] });

If load() rejects, the journal starts empty and calls save() on the next edit. Guarding save() with a loaded flag prevents a failed initial request from overwriting stored journal records on your server.

Widgets

Both the compact journal panel and the full-screen analytics view can be mounted outside a workspace as standalone components (see Standalone widgets).

createJournalPanel(props) creates the compact side panel widget. Its tools element contains the account selector, Add trade button, and Maximize button.

PropDescription
controllerRequired. JournalController managing journal data and selection state.
symbolDefault symbol prefilled when opening Add trade.
hostPortal container for menus and dialogs. Defaults to the widget's root element.
iconsAccessor returning a symbol icon source (() => chart.data or any object implementing symbolIcon(symbol)).
onMaximizeCallback invoked to open the full journal view, passing an optional target (trade key or date). Omit to hide Maximize.
onShowTradeCallback invoked with a reconstructed trade so host code can frame it on a chart. Omit to hide per-trade chart buttons.
onNotifyCallback invoked with (message, kind) for status feedback.

createJournalView(props) creates the full-screen analytics dashboard. It accepts controller, symbol, host, icons, onShowTrade, and onNotify, along with onMinimize and onClose (each button renders only when its callback is provided). Call view.open(target) to navigate directly to a specific trade or date.

When running outside a workspace, connect a TradingController's broker manually by calling journal.syncBroker(trading.broker).

Keyboard shortcuts

KeysAction
EscapeCloses the maximized journal view and returns to the chart (ignored when typing in an input)

On this page