local strategy

AGENTS.md

@@ -41,10 +41,13 @@ src/
 │   ├── custom_timeframe_generator.py  # 37m, 148m, 1d aggregation
 │   ├── indicator_engine.py      # SMA/EMA computation & storage
 │   ├── brain.py                 # Strategy evaluation & decision logging
-│   └── backtester.py            # Historical replay driver
-└── api/
-    ├── server.py                # FastAPI app, endpoints for data/backtests
-    └── dashboard/static/index.html  # Real-time web dashboard
+│   └── backtester.py            # Historical replay driver (server-side)
+├── api/
+│   ├── server.py                # FastAPI app, endpoints for data/backtests
+│   └── dashboard/static/index.html  # Real-time web dashboard with client-side simulation
+└── strategies/
+    ├── base.py                  # Base strategy interface
+    └── ma_strategy.py           # Configurable MA strategy (period: 5-500)
 config/data_config.yaml          # Operational config & indicator settings
 docker/                          # Docker orchestration & init-scripts
 scripts/                         # Deploy, backup, & utility scripts
@@ -52,17 +55,30 @@ scripts/                         # Deploy, backup, & utility scripts
 
 ## Architecture & Data Flow
 
+### Live Trading (Server-Side)
 ```
 Live: WS -> Buffer -> DB -> CustomTF -> IndicatorEngine -> Brain -> Decisions
                                               │             │
 Backtest: DB (History) -> Backtester ─────────┴─────────────┘
 ```
 
+### Client-Side Simulation (Dashboard)
+```
+User Input -> API /candles/bulk -> Browser (ClientStrategyEngine) -> Chart Visualization
+                    ↓                                              ↓
+            Historical Data                                Buy/Sell Markers
+```
+
 - **Stateless Logic**: `IndicatorEngine` and `Brain` are driver-agnostic. They read from DB
   and write to DB, unaware if the trigger is live WS or backtest replay.
 - **Consistency**: Indicators are computed exactly the same way for live and backtest.
 - **Visualization**: Dashboard queries `indicators` and `decisions` tables directly.
   Decisions contain a JSON snapshot of indicators at the moment of decision.
+- **Client-Side Simulation**: All strategy simulations run in the browser using `ClientStrategyEngine`.
+  The server only provides historical candle data via API. This minimizes server load and allows
+  interactive backtesting with configurable parameters (MA period 5-500).
+- **Full Historical Display**: After simulation, the chart displays the complete date range used,
+  not just the default 1000 recent candles.
 
 ## Key Dataclasses
 
@@ -109,6 +125,32 @@ class Decision:                  # Brain output
 - **Logging**: Use `logger = logging.getLogger(__name__)`.
 - **Config**: Load from `config/data_config.yaml` or env vars.
 
+## Strategy Configuration
+
+The system uses a single configurable Moving Average strategy (`ma_strategy`) with a dynamic period (5-500).
+
+### Strategy Files
+- `src/strategies/base.py` - Base strategy interface with `SignalType` enum
+- `src/strategies/ma_strategy.py` - Configurable MA strategy implementation
+
+### Client-Side vs Server-Side
+
+| Feature | Client-Side (Dashboard) | Server-Side (CLI/API) |
+|---------|------------------------|----------------------|
+| **Purpose** | Interactive simulation | Production backtesting |
+| **Strategy** | Single configurable MA (period 5-500) | Configurable via strategy registry |
+| **Indicators** | Calculated in browser (SMA, RSI, etc.) | Pre-computed in database |
+| **Data Flow** | API → Browser → Chart | DB → Backtester → DB |
+| **Performance** | Fast, interactive | Thorough, historical |
+
+### Simulation Workflow
+1. User selects date range and MA period (5-500) in dashboard sidebar
+2. Browser fetches full historical data from `/api/v1/candles/bulk`
+3. `ClientStrategyEngine` calculates indicators client-side using JavaScript
+4. Simulation runs on complete dataset, generating buy/sell signals
+5. Chart updates to show full historical range with trade markers
+6. Results displayed in sidebar (win rate, P&L, profit factor)
+
 ## Common Tasks
 
 ### Add New Indicator