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



User state in Vela Pro falls into two categories: a single **workspace state document** per workspace, and **independent stores** for data that is not scoped to a single layout. By default, independent stores write to `localStorage`, and the workspace state document writes to `localStorage` once `persist` is enabled. You can replace each store with a custom adapter or port to persist state per user on your backend.

## State inventory [#state-inventory]

### Workspace state document [#workspace-state-document]

These entries are scoped to a layout. Configuring `persist` and `storage` on `VelaWorkspace` saves and restores all of them together.

| State                                                                                                   | Document field                                             |
| ------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| Grid layout, splitter sizes, active chart, sync links, and time zone                                    | `layout`, `trackSizes`, `activeCellId`, `sync`, `timezone` |
| Per-chart symbol, timeframe, chart type, session, bar depth, status line, watermark, and legend toggles | `charts[i]`                                                |
| Chart settings (colors, scales, grid, margins) and chart-type settings (Footprint, TPO)                 | `charts[i].rendererConfig`                                 |
| Drawings on each chart for its active symbol                                                            | `charts[i].drawings`                                       |
| Built-in indicators and manifest scripts, including modified inputs and visibility state                | `charts[i].indicators`                                     |
| Scripts added from the indicator menu, including their source code                                      | `charts[i].ext['velapro.indicators']`                      |
| Favorite drawing tools                                                                                  | `favorites`                                                |
| Favorite timeframes                                                                                     | `timeframeFavorites`                                       |
| Drawing tool defaults, saved styles, magnet mode, and stay-in-drawing-mode                              | `drawingTools`                                             |
| Side panels (active panel, resized widths, and pinned panels)                                           | `panels`                                                   |
| Bottom dock open state, active panel, and height                                                        | `ext['velapro.bottomDock']`                                |
| Order book settings (DOM columns, depth mode, combined book)                                            | `ext['velapro.orderbook']`                                 |
| Trading settings (modified display settings, safety settings, presets, order size)                      | `ext['velapro.trading']`                                   |
| Calendar settings (active tab and impact filter)                                                        | `ext['velapro.calendar']`                                  |

### Independent stores [#independent-stores]

| State                                                        | Default `localStorage` key                                                                    | Scope                | Configuration option or port                                                                                                       |
| ------------------------------------------------------------ | --------------------------------------------------------------------------------------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| Per-symbol drawings across every symbol opened on a chart    | `vela-pro.drawings:<chart>:<symbol>`, one entry per chart and symbol                          | Chart key and symbol | `symbolDrawings: { storage }`                                                                                                      |
| Indicator templates                                          | `velapro.indicatorTemplates`                                                                  | User                 | `indicatorTemplates: { storage }`                                                                                                  |
| Favorite indicators and scripts starred in the code editor   | `vela-pro-indicator-favorites`                                                                | User                 | `indicatorLibrary: { favorites }`                                                                                                  |
| Code editor draft                                            | `vela-pro-editor`                                                                             | User                 | `codeEditor: { storage, persist }`                                                                                                 |
| Watchlists, plus column, sparkline, and detail-panel toggles | `velapro.watchlists`                                                                          | User                 | `watchlist: { storage }` (`WatchlistStorage` port)                                                                                 |
| Alerts and alert firing log                                  | `vela-pro.alerts`                                                                             | User                 | `alerts: { backend }` (`AlertsBackend` port)                                                                                       |
| Journal accounts, fills, annotations, and notes              | `vela-pro.journal`                                                                            | User                 | `journal({ store })` (`JournalStore` port)                                                                                         |
| Paper trading accounts                                       | `vela-pro.paper`, `vela-pro.paper:accounts`, and `vela-pro.paper:<account>` per added account | Browser              | `trading({ paper: { persist } })` renames the key or keeps accounts in memory. Live accounts reside at your broker (`Broker` port) |
| Replay bar position and docked or floating state             | `vela-pro.replay.bar-position`, `vela-pro.replay.docked`                                      | Browser              | Browser-only (not configurable)                                                                                                    |
| Indicator menu view mode (cards or list)                     | `velapro.indicators.layout`                                                                   | Browser              | Browser-only (not configurable)                                                                                                    |

User-scoped stores are isolated per signed-in user only after you connect them to your backend. With the default `localStorage` adapters, everyone using the same browser profile shares the stored data.

## Workspace state document [#workspace-state-document-1]

`workspace.getState()` returns the workspace state document, and `workspace.applyState()` restores it as a single JSON object covering the layout and every chart in the workspace. When `persist` is enabled, the workspace writes the document through a **storage adapter** (defaulting to `localStorage` under the `vela-workspace` key) and restores it during construction.

Vela Pro features and modules with layout-level preferences store their settings inside the document's `ext` maps (one at the document root and one per chart). Enabling `persist: true` therefore preserves settings such as order book columns and trading presets automatically. See [Layouts and chart state](/vela-pro/persistence/layouts) for the document schema and [Plugin state](/vela-pro/persistence/stores/plugin-state) to register custom state handlers.

## Independent stores [#independent-stores-1]

State that spans multiple layouts is stored outside the workspace state document:

* **Per-symbol drawings** persist across symbol changes. While the state document holds one drawing set per chart for its active symbol, the per-symbol store keeps a separate set for every symbol opened on that chart and restores it when the user switches back. See [Drawing persistence](/vela-pro/persistence/stores/drawings).
* **Indicator templates and favorites** apply across layouts so a template saved in one layout is available in every other layout.
* **Module data** represents user records rather than layout preferences. Watchlists, alerts, and journal entries remain consistent regardless of which layout is active and can render inside standalone widgets on pages without a workspace.

Each independent store accepts a small `storage` adapter for built-in features or a typed port interface for domain modules, defaulting to `localStorage`.

## Transient state [#transient-state]

| Transient state                          | Behavior on reload                                                                                                                                                                                                                                                               |
| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Visible range (scroll position and zoom) | Never persisted. The `visibleRange` option frames the initial load of a newly created chart only.                                                                                                                                                                                |
| Historical bars                          | The state document records each chart's symbol, provider, and timeframe, while OHLCV bars are fetched from your data provider on every load.                                                                                                                                     |
| Theme and locale                         | Not stored in the state document. Each chart's `rendererConfig` preserves plot colors, while the surrounding interface follows the `theme` and locale options passed at construction. Persist the user's preference in your application and pass it when creating the workspace. |
| Maximized chart or panel                 | Resets to the full multi-chart layout after reload.                                                                                                                                                                                                                              |
| Drawing groups in the object tree        | Kept in memory for the lifetime of the chart instance.                                                                                                                                                                                                                           |
| Scripts executed from the code editor    | The editor text is saved as a draft, but indicators added directly by running code in the editor are excluded from the state document. See [Indicator persistence](/vela-pro/persistence/stores/indicators#non-persisted-scripts) for details.                                   |

## Moving storage to a backend [#moving-storage-to-a-backend]

<Steps>
  <Step title="Configure a workspace storage adapter">
    Pass `persist` and a `storage` object implementing `get` and `set` to `new VelaWorkspace(...)`. This routes the workspace state document and all layout-level `ext` settings to your backend.
  </Step>

  <Step title="Configure feature stores and module ports">
    Pass custom storage adapters and module ports to `enableVelaPro()` for `symbolDrawings`, `indicatorTemplates`, `indicatorLibrary`, `codeEditor`, and the `watchlist`, `alerts`, and `journal` modules.
  </Step>
</Steps>

See [Server-side storage](/vela-pro/persistence/backend) for a complete implementation covering both steps.

## Related [#related]

* [Configuration precedence](/vela-pro/persistence/precedence)
* [Workspace state and persistence in Vela's open-source core](/vela/user/workspace#state--persistence)
