update docs (#78)

eeiaao · web-flow · commit e92475228b0f · 2025-12-28T23:42:54.000+03:00
diff --git a/docs/architecture.md b/docs/architecture.md
@@ -26,7 +26,7 @@ Defines **pure interfaces** with no internal state. These are the contracts your
 
 * `Engine`: orchestrates startup and shutdown
 * `NLevelOrderBook`: in-memory order book with tick-aligned price levels
-* `CandleAggregator`: aggregates trades into fixed-interval OHLCV candles
+* `BarAggregator`: aggregates trades into fixed-interval OHLCV bars
 * `SymbolRegistry`: maps `(exchange:symbol)` pairs to compact `SymbolId`
 * `EventBus`: Disruptor-style ring buffer for high-throughput event delivery
 * `BookUpdateEvent`, `TradeEvent`: pooled, reusable market data structures
diff --git a/docs/components/book/bus/trade_bus.md b/docs/components/book/bus/trade_bus.md
@@ -19,7 +19,7 @@ bool configureTradeBusForPerformance(TradeBus& bus, bool enablePerformanceOptimi
 |----------|-------------------------------------------------------------------------|
 | Payload  | Direct delivery of `TradeEvent` instances (no wrapping or pooling).     |
 | Pattern  | Disruptor-style ring buffer with lock-free sequencing.                  |
-| Usage    | Used by connectors, aggregators (e.g., `CandleAggregator`), and strategies.|
+| Usage    | Used by connectors, aggregators (e.g., `BarAggregator`), and strategies.|
 
 ## Factory Functions
 
diff --git a/docs/components/book/events/trade_event.md b/docs/components/book/events/trade_event.md
@@ -25,6 +25,6 @@ struct TradeEvent {
 
 ## Notes
 
-* Used by `CandleAggregator`, PnL trackers, and all signal generation components.
+* Used by `BarAggregator`, PnL trackers, and all signal generation components.
 * Designed for ultra-low-latency delivery; no heap allocation involved.
 * Stateless container — no logic beyond encapsulation.
diff --git a/docs/components/book/trade.md b/docs/components/book/trade.md
@@ -32,6 +32,6 @@ struct Trade
 ## Notes
 
 * Emitted via `TradeEvent` through `TradeBus`.
-* Serves as input for candle aggregation, PnL tracking, flow analysis, and latency metrics.
+* Serves as input for bar aggregation, PnL tracking, flow analysis, and latency metrics.
 * `instrument` allows immediate filtering without a registry lookup in hot paths.
 * Uses `UnixNanos` (int64_t nanoseconds) for precise exchange timestamps.
diff --git a/docs/components/common.md b/docs/components/common.md
@@ -72,7 +72,7 @@ Built on top of the `Decimal` template for safe, precise arithmetic.
 | ---------- | ----- | -------------------------------------------- |
 | `Price`    | 1e-6  | Decimal representation of price.             |
 | `Quantity` | 1e-6  | Decimal quantity (e.g. number of contracts). |
-| `Volume`   | 1e-6  | Price × Quantity, used in candle bars etc.   |
+| `Volume`   | 1e-6  | Price × Quantity, used in bars etc.   |
 
 All three types use `Decimal<Tag, 1'000'000, 1>` internally, ensuring:
 
diff --git a/docs/components/engine/abstract_subsystem.md b/docs/components/engine/abstract_subsystem.md
@@ -27,7 +27,7 @@ public:
 ## Notes
 
 * Methods have default empty implementations, allowing derived classes to override only what they need.
-* Used by core modules like `CandleAggregator`, `Strategy`, `ExecutionTracker`, `SymbolRegistry`, etc.
+* Used by core modules like `BarAggregator`, `Strategy`, `ExecutionTracker`, `SymbolRegistry`, etc.
 * Lifecycle is typically orchestrated by the engine or test harness.
 * No assumptions about threading — start/stop are always externally coordinated.
 
diff --git a/docs/components/engine/event_dispatcher.md b/docs/components/engine/event_dispatcher.md
@@ -24,7 +24,7 @@ struct EventDispatcher<pool::Handle<T>> {
 | ----------------- | ------------------------------------------------------------- |
 | `BookUpdateEvent` | `IMarketDataSubscriber::onBookUpdate()`                       |
 | `TradeEvent`      | `IMarketDataSubscriber::onTrade()`                            |
-| `CandleEvent`     | `IMarketDataSubscriber::onCandle()`                           |
+| `BarEvent`        | `IMarketDataSubscriber::onBar()`                              |
 | `OrderEvent`      | `IOrderExecutionListener::onOrderFilled()` via `dispatchTo()` |
 | `pool::Handle<T>` | Unwraps and forwards to `EventDispatcher<T>`                  |
 
diff --git a/docs/components/strategy/abstract_strategy.md b/docs/components/strategy/abstract_strategy.md
@@ -17,7 +17,7 @@ public:
 
 | Inherits From        | Responsibilities                                         |
 |----------------------|----------------------------------------------------------|
-| `IMarketDataSubscriber` | Receives `TradeEvent`, `BookUpdateEvent`, `CandleEvent`. |
+| `IMarketDataSubscriber` | Receives `TradeEvent`, `BookUpdateEvent`, `BarEvent`. |
 | `ISubsystem`         | Enables coordinated `start()` / `stop()` during engine run. |
 
 ## Implementation
diff --git a/docs/explanation/architecture.md b/docs/explanation/architecture.md
@@ -33,11 +33,11 @@ flowchart TD
     subgraph EventBuses[Event Buses - Disruptor Ring Buffers]
         TB[TradeBus]
         BB[BookUpdateBus]
-        CB[CandleBus]
+        CB[BarBus]
     end
 
     subgraph Aggregators
-        CA[CandleAggregator]
+        CA[BarAggregator]
     end
 
     subgraph Strategies
@@ -102,10 +102,11 @@ All buses use the Disruptor pattern (see [The Disruptor Pattern](disruptor.md)):
 |-----|------------|---------|
 | `TradeBus` | `TradeEvent` | Individual trades |
 | `BookUpdateBus` | `pool::Handle<BookUpdateEvent>` | Order book snapshots/deltas |
-| `CandleBus` | `CandleEvent` | OHLCV candles |
+| `BarBus` | `BarEvent` | OHLCV bars |
 | `OrderExecutionBus` | `OrderEvent` | Order state changes |
 
 Key characteristics:
+
 - Lock-free ring buffer
 - Single producer, multiple consumers
 - Consumers run in dedicated threads
@@ -127,6 +128,7 @@ public:
 ```
 
 Connectors:
+
 - Parse exchange-specific wire protocols
 - Convert to FLOX event types
 - Publish to event buses
@@ -145,11 +147,13 @@ public:
 ```
 
 From `IMarketDataSubscriber`:
+
 - `onTrade(const TradeEvent&)`
 - `onBookUpdate(const BookUpdateEvent&)`
-- `onCandle(const CandleEvent&)`
+- `onBar(const BarEvent&)`
 
 From `ISubsystem`:
+
 - `start()`
 - `stop()`
 
@@ -168,9 +172,10 @@ public:
 ```
 
 Subsystems include:
+
 - Event buses
 - Strategies
-- Aggregators (e.g., CandleAggregator)
+- Aggregators (e.g., BarAggregator)
 - Execution trackers
 - Custom components
 
@@ -185,6 +190,7 @@ auto id = registry.getSymbolId("binance", "BTCUSDT");
 ```
 
 Benefits:
+
 - Fast comparison (integer vs string)
 - Compact event structures
 - Consistent across components
@@ -238,6 +244,7 @@ bus.setupOptimalConfiguration(EventBus::ComponentType::MARKET_DATA);
 ```
 
 This:
+
 - Pins consumer threads to isolated cores
 - Sets real-time scheduling priority
 - Enables NUMA-aware core assignment
diff --git a/docs/explanation/integration-flow.md b/docs/explanation/integration-flow.md
@@ -139,7 +139,7 @@ tradeBus->subscribe(metrics.get(), /*optional=*/true);
 **Common subscribers:**
 
 - Trading strategies
-- Data aggregators (candles, VWAP)
+- Data aggregators (bars, VWAP)
 - Metric collectors
 - Risk modules
 - Loggers
diff --git a/docs/how-to/README.md b/docs/how-to/README.md
@@ -8,6 +8,7 @@ Solve specific problems. Assumes you know the basics.
 |-------|---------|
 | [Backtesting](backtest.md) | Run strategy backtests on historical data |
 | [Grid Search Optimization](grid-search.md) | Find optimal strategy parameters |
+| [Bar Aggregation Pipeline](bar-aggregation.md) | Pre-aggregate bars for fast backtesting |
 | [Advanced Orders](advanced-orders.md) | Use stop-loss, take-profit, brackets |
 | [Multi-Exchange Trading](multi-exchange-trading.md) | Trade across multiple exchanges with aggregation and routing |
 | [CI Configuration](ci.md) | Understand the CI pipeline |
diff --git a/docs/how-to/bar-aggregation.md b/docs/how-to/bar-aggregation.md
@@ -168,7 +168,7 @@ Flox supports multiple bar types through different policies:
 | Volume | threshold | Close bar when volume exceeds threshold |
 | Renko | brick size | Fixed price movement bars |
 | Range | range | Close when high-low exceeds range |
-| HeikinAshi | interval | Heikin-Ashi smoothed candles |
+| HeikinAshi | interval | Heikin-Ashi smoothed bars |
 
 Example with tick bars:
 
diff --git a/docs/index.md b/docs/index.md
@@ -38,6 +38,7 @@
 | CPU affinity support | Pin threads to isolated cores |
 | Multi-exchange trading | [CEX coordination](components/cex/index.md) with aggregation and smart routing |
 | Binary replay system | Record live data, replay for backtesting |
+| Grid search optimization | Parallel parameter optimization with mmap-based bar storage |
 | Type-safe primitives | Strong types for Price, Quantity, SymbolId |
 | Modular architecture | Use only what you need |
 
diff --git a/docs/reference/README.md b/docs/reference/README.md
@@ -40,5 +40,5 @@ using SubscriberId = uintptr_t;
 |-----|------------|--------|
 | `TradeBus` | `TradeEvent` | `flox/book/bus/trade_bus.h` |
 | `BookUpdateBus` | `pool::Handle<BookUpdateEvent>` | `flox/book/bus/book_update_bus.h` |
-| `CandleBus` | `CandleEvent` | `flox/aggregator/bus/candle_bus.h` |
+| `BarBus` | `BarEvent` | `flox/aggregator/bus/bar_bus.h` |
 | `OrderExecutionBus` | `OrderEvent` | `flox/execution/bus/order_execution_bus.h` |
diff --git a/docs/reference/api/book/bus/trade_bus.md b/docs/reference/api/book/bus/trade_bus.md
@@ -19,7 +19,7 @@ using TradeBus = EventBus<TradeEvent, AsyncPolicy<TradeEvent>>;
 |----------|-------------------------------------------------------------------------|
 | Payload  | Direct delivery of `TradeEvent` instances (no wrapping or pooling).     |
 | Mode     | Chooses between `SyncPolicy` and `AsyncPolicy` via compile-time macro. |
-| Usage    | Used by connectors, aggregators (e.g., `CandleAggregator`), and strategies.|
+| Usage    | Used by connectors, aggregators (e.g., `BarAggregator`), and strategies.|
 
 ## Notes
 * `SyncPolicy` guarantees deterministic tick-to-tick replay for simulation/backtesting.
diff --git a/docs/reference/api/book/events/trade_event.md b/docs/reference/api/book/events/trade_event.md
@@ -25,6 +25,6 @@ struct TradeEvent {
 
 ## Notes
 
-* Used by `CandleAggregator`, PnL trackers, and all signal generation components.
+* Used by `BarAggregator`, PnL trackers, and all signal generation components.
 * Designed for ultra-low-latency delivery; no heap allocation involved.
 * Stateless container — no logic beyond encapsulation.
diff --git a/docs/reference/api/book/trade.md b/docs/reference/api/book/trade.md
@@ -31,7 +31,7 @@ struct Trade {
 ## Notes
 
 * Emitted via `TradeEvent` through `TradeBus`.
-* Serves as input for candle aggregation, PnL tracking, flow analysis, and latency metrics.
+* Serves as input for bar aggregation, PnL tracking, flow analysis, and latency metrics.
 * `instrument` allows immediate filtering without a registry lookup in hot paths.
 * Uses `UnixNanos` (nanosecond precision) for accurate timestamp handling across exchanges.
 
diff --git a/docs/reference/api/common.md b/docs/reference/api/common.md
@@ -116,7 +116,7 @@ using Volume = Decimal<VolumeTag, 100'000'000, 1>;
 |------|-------|-------------|
 | `Price` | 1e-6 | Decimal representation of price. |
 | `Quantity` | 1e-6 | Decimal quantity (e.g. number of contracts). |
-| `Volume` | 1e-6 | Price × Quantity, used in candle bars etc. |
+| `Volume` | 1e-6 | Price × Quantity, used in bars etc. |
 
 All three types use `Decimal<Tag, 1'000'000, 1>` internally, ensuring:
 
diff --git a/docs/reference/api/engine/abstract_subsystem.md b/docs/reference/api/engine/abstract_subsystem.md
@@ -25,6 +25,6 @@ public:
 
 ## Notes
 
-* Used by core modules like `CandleAggregator`, `Strategy`, `ExecutionTracker`, etc.
+* Used by core modules like `BarAggregator`, `Strategy`, `ExecutionTracker`, etc.
 * Lifecycle is typically orchestrated by the engine or test harness.
 * No assumptions about threading — start/stop are always externally coordinated.
diff --git a/docs/reference/api/engine/event_dispatcher.md b/docs/reference/api/engine/event_dispatcher.md
@@ -24,7 +24,7 @@ struct EventDispatcher<pool::Handle<T>> {
 | ----------------- | ------------------------------------------------------------- |
 | `BookUpdateEvent` | `IMarketDataSubscriber::onBookUpdate()`                       |
 | `TradeEvent`      | `IMarketDataSubscriber::onTrade()`                            |
-| `CandleEvent`     | `IMarketDataSubscriber::onCandle()`                           |
+| `BarEvent`        | `IMarketDataSubscriber::onBar()`                              |
 | `OrderEvent`      | `IOrderExecutionListener::onOrderFilled()` via `dispatchTo()` |
 | `pool::Handle<T>` | Unwraps and forwards to `EventDispatcher<T>`                  |
 
diff --git a/docs/reference/api/replay/market_data_recorder.md b/docs/reference/api/replay/market_data_recorder.md
@@ -22,7 +22,7 @@ public:
   SubscriberId id() const override;
   void onBookUpdate(const BookUpdateEvent& event) override;
   void onTrade(const TradeEvent& event) override;
-  void onCandle(const CandleEvent& event) override;
+  void onBar(const BarEvent& event) override;
 
   // IMarketDataRecorder
   void setOutputDir(const std::filesystem::path& dir) override;
@@ -35,7 +35,7 @@ public:
 ## Purpose
 
 * Provide a ready-to-use market data recording solution.
-* Subscribe to `TradeBus`, `BookUpdateBus`, and `CandleBus` for automatic recording.
+* Subscribe to `TradeBus`, `BookUpdateBus`, and `BarBus` for automatic recording.
 * Abstract away low-level binary format details.
 
 ## Configuration
@@ -54,7 +54,7 @@ public:
 | `stop()` | Stop recording and close current segment. |
 | `onBookUpdate(event)` | Record a book update event. |
 | `onTrade(event)` | Record a trade event. |
-| `onCandle(event)` | Record a candle event (currently no-op). |
+| `onBar(event)` | Record a bar event (currently no-op). |
 | `setOutputDir(dir)` | Change output directory (takes effect on next rotation). |
 | `flush()` | Flush buffers to disk. |
 | `stats()` | Returns recording statistics. |
diff --git a/docs/reference/api/strategy/abstract_strategy.md b/docs/reference/api/strategy/abstract_strategy.md
@@ -16,7 +16,7 @@ public:
 
 | Inherits From        | Responsibilities                                         |
 |----------------------|----------------------------------------------------------|
-| `IMarketDataSubscriber` | Receives `TradeEvent`, `BookUpdateEvent`, `CandleEvent`. |
+| `IMarketDataSubscriber` | Receives `TradeEvent`, `BookUpdateEvent`, `BarEvent`. |
 | `ISubsystem`         | Enables coordinated `start()` / `stop()` during engine run. |
 
 ## Notes
diff --git a/docs/reference/replay.md b/docs/reference/replay.md
@@ -5,6 +5,7 @@ Recording, playback, and segment operations.
 ## Binary Format
 
 FLOX uses a custom binary format (`.floxlog`) optimized for:
+
 - Sequential writes (recording)
 - Sequential and indexed reads (replay)
 - Optional LZ4 compression
diff --git a/docs/tutorials/README.md b/docs/tutorials/README.md
@@ -10,18 +10,20 @@ Step-by-step lessons to get you productive with FLOX.
 
 ## Getting Started
 
-| Tutorial | Time | What You'll Learn |
-|----------|------|-------------------|
-| [Quickstart](quickstart.md) | 5 min | Build FLOX and run the demo |
-| [First Strategy](first-strategy.md) | 15 min | Write a simple trading strategy |
-| [Recording Data](recording-data.md) | 10 min | Capture live market data to disk |
-| [Backtesting](backtesting.md) | 10 min | Replay recorded data through your strategy |
+| Tutorial | What You'll Learn |
+|----------|-------------------|
+| [Quickstart](quickstart.md) | Build FLOX and run the demo |
+| [First Strategy](first-strategy.md) | Write a simple trading strategy |
+| [Multi-Timeframe Strategy](multi-timeframe-strategy.md) | Build strategies using multiple bar timeframes |
+| [Recording Data](recording-data.md) | Capture live market data to disk |
+| [Backtesting](backtesting.md) | Replay recorded data through your strategy |
 
 ## Recommended Order
 
 1. **Quickstart** — Verify your environment works
 2. **First Strategy** — Understand the core programming model
-3. **Recording Data** — Set up market data capture
-4. **Backtesting** — Test strategies against historical data
+3. **Multi-Timeframe Strategy** — Work with multiple bar timeframes
+4. **Recording Data** — Set up market data capture
+5. **Backtesting** — Test strategies against historical data
 
 After completing these tutorials, move on to [How-To Guides](../how-to/README.md) for specific tasks or [Explanation](../explanation/README.md) for deeper understanding.
diff --git a/docs/tutorials/multi-timeframe-strategy.md b/docs/tutorials/multi-timeframe-strategy.md
@@ -20,7 +20,7 @@ A momentum strategy that:
 2. Uses **M5** (5-minute) bars to identify pullbacks
 3. Uses **M1** (1-minute) bars for entry timing
 
-**Entry logic**: Buy when H1 is bullish, M5 shows a pullback, and M1 prints a reversal candle.
+**Entry logic**: Buy when H1 is bullish, M5 shows a pullback, and M1 prints a reversal bar.
 
 ## Step 1: Project Setup
 
@@ -107,10 +107,10 @@ void onBar(const BarEvent& ev) override
   // 1. Check H1 trend
   bool h1Bullish = h1->close > h1_prev->close;
 
-  // 2. Check M5 pullback (bearish candle in uptrend)
+  // 2. Check M5 pullback (bearish bar in uptrend)
   bool m5Pullback = m5->close < m5->open;
 
-  // 3. Check M1 reversal (bullish candle after pullback)
+  // 3. Check M1 reversal (bullish bar after pullback)
   bool m1Reversal = m1->close > m1->open;
 
   // Generate signal
@@ -234,7 +234,7 @@ class MTFMomentumStrategy : public IMarketDataSubscriber
     bool m5Pullback = m5->close < m5->open;   // Bearish M5 in uptrend
     bool m5Rally = m5->close > m5->open;      // Bullish M5 in downtrend
 
-    // Entry candle
+    // Entry bar
     bool m1BullishReversal = m1->close > m1->open;
     bool m1BearishReversal = m1->close < m1->open;
 
diff --git a/docs/tutorials/recording-data.md b/docs/tutorials/recording-data.md
@@ -10,6 +10,7 @@ Capture live market data to disk for later replay and backtesting.
 ## 1. BinaryLogWriter Overview
 
 FLOX records market data in a custom binary format optimized for:
+
 - Sequential writes (no random access during recording)
 - Fast sequential reads during replay
 - Optional LZ4 compression
diff --git a/docs/usage/strategies.md b/docs/usage/strategies.md
@@ -17,6 +17,7 @@ public:
 ```
 
 `IStrategy` inherits from:
+
 - `ISubsystem` — provides `start()` and `stop()` lifecycle hooks
 - `IMarketDataSubscriber` — provides market data callbacks and `id()` for routing
 
@@ -27,7 +28,7 @@ From `IMarketDataSubscriber`:
 ```cpp
 virtual void onBookUpdate(const BookUpdateEvent& ev) {}
 virtual void onTrade(const TradeEvent& ev) {}
-virtual void onCandle(const CandleEvent& ev) {}
+virtual void onBar(const BarEvent& ev) {}
 ```
 
 ## Lifecycle
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -79,6 +79,7 @@ nav:
       - tutorials/README.md
       - Quickstart: tutorials/quickstart.md
       - First Strategy: tutorials/first-strategy.md
+      - Multi-Timeframe Strategy: tutorials/multi-timeframe-strategy.md
       - Recording Data: tutorials/recording-data.md
       - Backtesting: tutorials/backtesting.md
       - Run Demo: tutorials/demo.md
