# Overview (/vela-pro/modules/overview)



Vela Pro includes six domain modules for market monitoring, alerting, execution, and post-trade analysis: Watchlist, Alerts, Order Book, Trading, Journal, and Calendar. Each module is distributed as a separate package under `plugins/` in the Vela Pro repository. Watchlist, Alerts, and Order Book are enabled by default when you call `enableVelaPro()`, while Trading, Journal, and Calendar are opt-in. Every module connects to your backend or brokerage through a typed port interface.

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

enableVelaPro({
    watchlist: { defaultSymbols: ['BTCUSDT', 'ETHUSDT'] }, // configure a default module
    orderBook: false, // disable a default module
    plugins: [trading(), journal()], // register opt-in modules
});

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

In the SDK types, modules are represented as plugins. You register opt-in modules in the `plugins` array and author custom modules with `definePlugin`.

## Available modules [#available-modules]

| Module                                             | Package                       | Availability              | Enabled via                       | Panel ID                                              | Controller              |
| -------------------------------------------------- | ----------------------------- | ------------------------- | --------------------------------- | ----------------------------------------------------- | ----------------------- |
| [Watchlist](/vela-pro/modules/catalog/watchlist)   | `@luxalgo/vela-pro-watchlist` | Enabled by default        | `watchlist` option                | `vela-pro.watchlist`                                  | `watchlistController()` |
| [Alerts](/vela-pro/modules/catalog/alerts)         | `@luxalgo/vela-pro-alerts`    | Enabled by default        | `alerts` option                   | `vela-pro.alerts`                                     | `alertsController()`    |
| [Order book](/vela-pro/modules/catalog/order-book) | `@luxalgo/vela-pro-dom`       | Enabled by default        | `orderBook` option                | `vela-pro.orderbook`                                  | None                    |
| [Trading](/vela-pro/modules/trading/overview)      | `@luxalgo/vela-pro-trading`   | Opt-in                    | `plugins: [trading()]`            | `vela-pro.order` and `vela-pro.trading` (bottom dock) | `tradingController()`   |
| [Journal](/vela-pro/modules/catalog/journal)       | `@luxalgo/vela-pro-journal`   | Opt-in (requires Trading) | `plugins: [journal()]`            | `vela-pro.journal`                                    | `journalController()`   |
| [Calendar](/vela-pro/modules/catalog/calendar)     | `@luxalgo/vela-pro-calendar`  | Opt-in                    | `plugins: [calendar({ source })]` | `vela-pro.calendar`                                   | `calendarController()`  |

Most modules mount as side panels to the right of the chart area and add a toggle button to the side rail. The trading account panel (`vela-pro.trading`) mounts in the bottom dock beneath the charts instead.

## Configuration [#configuration]

### Default modules [#default-modules]

Watchlist, Alerts, and Order Book are enabled by default. Pass `false` to disable a module, or pass an options object to customize its configuration.

```ts
import { enableVelaPro } from '@luxalgo/vela-pro';

enableVelaPro({
    orderBook: false,
    alerts: { webhooks: true },
    watchlist: { defaultSymbols: ['BTCUSDT', 'AAPL'], width: 360 },
});
```

### Opt-in modules [#opt-in-modules]

See [Installation](/vela-pro/get-started/setup) for adding module packages to your project. Once installed, import each module factory and pass its return value in the `plugins` array.

```ts
import { enableVelaPro } from '@luxalgo/vela-pro';
import { calendar, type CalendarSource } from '@luxalgo/vela-pro-calendar';
import { journal } from '@luxalgo/vela-pro-journal';
import { trading } from '@luxalgo/vela-pro-trading';

declare const myCalendarSource: CalendarSource;

enableVelaPro({
    plugins: [
        trading({ paper: { initialBalance: 25_000 } }),
        journal({ timeZone: 'America/New_York' }),
        calendar({ source: myCalendarSource }),
    ],
});
```

Vela Pro resolves module dependencies automatically regardless of their order in `plugins`. For example, Journal depends on Trading and always installs after it. If a required dependency is missing, Vela Pro skips the dependent module and logs a console error starting with `[vela-pro] "journal" needs "trading", which is not installed`.

Call `enableVelaPro()` once before constructing any `VelaWorkspace`, because workspaces read the registered panels during construction. Subsequent calls to `enableVelaPro()` skip already-installed modules and do not apply updated options.

## Inter-module integration [#inter-module-integration]

Modules do not import one another directly. Instead, they discover peer modules through runtime APIs, so every module works standalone and unlocks combined workflows when paired.

| Primary module | Paired module   | Combined capability                                                                                                              |
| -------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| Order book     | Trading         | Click-to-trade execution on the DOM ladder, order chips that cancel resting orders, and a position chip that closes the position |
| Watchlist      | Alerts          | "Add alert…" entry in each symbol row's right-click menu                                                                         |
| Order book     | Alerts, Trading | Right-click context menu actions to place an order or create a price alert at any price level                                    |
| Journal        | Trading         | Automatic recording of broker fills into the journal as executions occur                                                         |

Cross-module capabilities activate only when both modules are installed. Without Trading, the DOM ladder remains read-only. Without Alerts, watchlist row menus omit the alert action.

## Controllers [#controllers]

A controller exposes a module's state, actions, and change notifications to application code. Each `*Controller()` function returns `null` until `enableVelaPro()` installs that module, so call it after initialization and guard against `null`.

```ts
import { VelaWorkspace } from '@luxalgo/vela/workspace';
import { BinanceProvider } from '@luxalgo/vela/providers/binance';
import { bottomDock, enableVelaPro } from '@luxalgo/vela-pro';
import { alertsController } from '@luxalgo/vela-pro-alerts';
import { trading, tradingController } from '@luxalgo/vela-pro-trading';
import { watchlistController } from '@luxalgo/vela-pro-watchlist';

enableVelaPro({ plugins: [trading()] });

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

watchlistController()?.add('ETHUSDT');
alertsController()?.create({
    symbol: 'BTCUSDT',
    condition: { kind: 'price', op: 'crossing-up', value: 80_000 },
});

const account = tradingController();
account?.onChange((what) => {
    if (what === 'broker') console.info(account.state().positions);
});

document.querySelector('#buy')?.addEventListener('click', () => {
    account?.trade('BTCUSDT', 'buy', { qty: 0.1 });
    bottomDock(workspace.context())?.open('vela-pro.trading');
});
```

Every controller provides `onChange(listener)`, which returns an unsubscribe function. Read the latest state from the controller inside your listener.

To open or close panels from code, use the workspace context. Call `workspace.context().togglePanel('vela-pro.watchlist', true)` for side panels and `bottomDock(ctx)?.open('vela-pro.trading')` for the trading panel in the bottom dock. Always drive module state through controllers rather than manipulating panel DOM elements.

## State and persistence [#state-and-persistence]

Modules separate UI preferences from domain data.

**UI preferences** are stored in the workspace state document when `persist` is enabled on `VelaWorkspace` (or when you manage serialization manually with `getState()` and `applyState()`). This includes Order Book columns, cumulative depth mode, and combined venue mode; Trading display settings, safety controls, presets, and order quantity; Calendar active tab and impact filter; the bottom dock's active panel and height; and side panel widths. Constructor options define initial defaults, and user changes take precedence once saved. See [Persistence](/vela-pro/persistence/overview) for full details.

**Domain data** (watchlists, alert rules and firing logs, paper trading accounts, and journal records) is read and written through each module's port interface. Where a browser default is included, it persists to `localStorage`.

## Ports [#ports]

A port is the TypeScript interface a module uses to communicate with external storage, market data, or brokerage services. Implement the corresponding port to persist user data on your backend, connect a live broker, or supply market events.

| Port               | Module                                             | Default implementation                        | Purpose                                                                            |
| ------------------ | -------------------------------------------------- | --------------------------------------------- | ---------------------------------------------------------------------------------- |
| `WatchlistStorage` | [Watchlist](/vela-pro/modules/catalog/watchlist)   | `LocalWatchlistStorage`                       | Persists symbol lists and list display settings                                    |
| `QuoteSource`      | [Watchlist](/vela-pro/modules/catalog/watchlist)   | `ProviderQuotes` (reads chart providers)      | Streams live quotes and fetches daily bars for the expanded view                   |
| `AlertsBackend`    | [Alerts](/vela-pro/modules/catalog/alerts)         | `LocalAlertsBackend`                          | Persists alert rules and the firing log                                            |
| `DepthFeed`        | [Order book](/vela-pro/modules/catalog/order-book) | None (implemented on your `DataProvider`)     | Streams order book snapshots and the trades tape                                   |
| `Broker`           | [Trading](/vela-pro/modules/trading/overview)      | `PaperBroker` (simulated account)             | Manages accounts, orders, positions, and executions                                |
| `JournalStore`     | [Journal](/vela-pro/modules/catalog/journal)       | `LocalJournalStore`                           | Persists journal accounts, fills, annotations, and daily notes                     |
| `CalendarSource`   | [Calendar](/vela-pro/modules/catalog/calendar)     | None (renders an empty state until connected) | Supplies economic releases, earnings, dividends, splits, IPOs, and market holidays |

## Related [#related]

* [Standalone widgets](/vela-pro/modules/widgets)
* [Broker integration](/vela-pro/modules/trading/broker)
* [Custom panels and widgets](/vela-pro/modules/extending/custom-widgets)
* [Custom modules](/vela-pro/modules/extending/custom-modules)
