# Guided Strategy Builder (Wizard) & Product Features

> Last Updated: 2026-02-20

## Overview
The Guided Strategy Builder is a productized, non-technical interface designed to allow customers to deploy safe, professional trading strategies without needing to understand technical indicators or JSON configuration.

## Core Architecture
- **Unified Logic**: Both the Advanced "Strategy Clusters" and the "Guided Wizard" use the same backend engine and database schema.
- **Dual Persona**:
  - **Admin Mode**: Full access to fine-grained parameters, raw rule controls, and marketplace publishing.
  - **Customer Mode**: Simplified 5-step wizard that auto-maps human intents to engine configurations.

---

## Featured Product Layers

### A. Preset Strategy Marketplace
A live, dynamic catalog that allows users to adopt approved strategy templates.
- **System Presets**: Hardcoded templates defined in `PresetRegistry.ts` (e.g., Top Performing Aggressive Bot, Low Volatility BTC Bot).
- **Admin-Published Templates**: Admins can publish any Strategy Cluster profile to the Marketplace via the **Publish (Share)** icon. These are stored in the `strategy_presets` Supabase table and fetched dynamically.
- **Mechanism**: Adopting a preset seeds the Wizard state with a validated template, allowing the user to customize capital/assets before deployment.
- **Contextual Intelligence**: The Marketplace tab now shows two live data panels above the strategy grid:
  - **🧠 Best AI Setups**: Top 5 symbols ranked by AIAnalysisRule confidence score.
  - **🔥 Top Volatile (24h)**: Top 6 most active symbols by absolute 24h price change.

### B. Education Layer (Explainability)
A frontend service that translates technical engine state into human-readable insights.
- **"Why didn't it trade?"**: Explains rule mismatch (e.g., "Matched 2/4 indicators") or session restrictions.
- **Recommended Actions**: Context-aware suggestions (e.g., "Strategy is paused, click play to resume").
- **Safety Indicators**: Real-time feedback on Daily Profit Targets being reached.

### C. Tiered Access Control
Product-tier gating for strategy creation and features.
- **Free**: Restricted to "Safe Growth" (100% pass ratio) and locked profit targets.
- **Pro**: Access to "Balanced" style and up to $100 daily profit targets.
- **Elite**: Unrestricted access, including "Aggressive" styles and higher profit targets.

### D. Live Pulse Ticker (Global)
A persistent 40px intelligence bar rendered just below the sticky header on **every tab**:
- Scrolling real-time ticker for all tracked symbols with 24h % change (green/red).
- Right-side "AI Top Picks" section showing the 3 highest-confidence AI signals at a glance.
- Provides a "Bloomberg Terminal" feel — live and active regardless of which tab is open.
- Component: `src/components/LivePulseTicker.tsx`

### E. My Strategies — Operational Intelligence Panels
The **My Strategies** tab includes two contextual panels between the header and strategy grid:
- **Recent Activity**: Last 5 system alerts filtered by type (signal 🚀, pulse ⏰, error ⚠️, info ℹ️) with relative timestamps.
- **Your Markets (24h)**: 24h volatility data **filtered exclusively to symbols the user's active strategies are trading** — personalized, not a global list.

---

## The Wizard Flow

### 1. Risk Style (Presets)
Instead of exposing rule pass ratios, we use "Risk Styles":
- **🛡️ Safe Growth**: 100% Voting Rules match required. (Free+)
- **⚖️ Balanced**: 90% Voting Rules match required. (Pro+)
- **🔥 Aggressive**: 70% Voting Rules match required. (Elite only)

### 2. Assets & Capital
- Users select from a curated list (BTC, ETH, SOL).
- Capital is bound to the `allocated_capital` schema property.
- Daily Profit Target uses the `dailyProfitTargetUsd` risk limit.

### 3. Trading Hours
Maps directly to the `SessionRule`. Users choose:
- **24/7** → sessions stored as `LDN,NY,TOK,SYD` → SessionRule detects all 4 and always passes.
- **London + New York** → `LDN,NY` → only passes during those sessions.
- **Asia only** → `TOK,SYD` → only passes during Asian hours.

### 4. Safety Injection (Automatic)
The wizard enforces several non-negotiable safety guards:
- **Mandatory Risk Rule**: The `RiskManagementRule` is always injected.
- **Automatic Stop Loss**: Configured via the `riskPerTrade` parameter.
- **Daily Recovery Halt**: Automatically sets a 5% max draw-down limit.

### 5. Review & Deploy
- Bot is created in **PAUSED** mode. User must manually activate from My Strategies tab.

---

## Admin: Publishing to Marketplace

Admins can convert any Strategy Cluster profile into a marketplace template:

1. Navigate to **🛡️ Strategy Clusters** (admin only tab).
2. Find the target profile card and click the **↗ (Share/Publish)** icon.
3. The system auto-detects risk style from `minRulePassRatio`, builds a payload, and inserts into `strategy_presets` table.
4. The template immediately appears in the **Strategy Marketplace** for all users.

**Database Table**: `public.strategy_presets` (see `schema/016_add_strategy_marketplace.sql`)
**RLS Policy**: Admins can write; all authenticated users can read.

---

## UI → JSON Mapping Strategy

| UI Component | JSON Path | Default/Value |
| :--- | :--- | :--- |
| Risk Style Option | `execution.minRulePassRatio` | `1.0`, `0.9`, or `0.7` |
| Capital Input | `allocated_capital` | (User Input) |
| Profit Target | `strategy_config.riskLimits.dailyProfitTargetUsd` | (User Input) |
| Trading Hours | `SessionRule.params.sessions` | `LDN,NY,TOK,SYD` (24/7), `LDN,NY`, or `TOK,SYD` |
| Safety notice | `strategy_config.rules[RiskManagement]...` | `mandatory` |
| Final Action | `is_active` | `false` (Paused on creation) |
| Publish to Marketplace | `strategy_presets` table | Admin only |
