(feat) update pages

pages/performance/README.md

@@ -0,0 +1,231 @@
+# Performance Module
+
+## Page Purpose and Functionality
+
+The Performance module provides comprehensive analytics and visualization tools for evaluating trading bot performance. It offers detailed insights into trade execution, profitability, risk metrics, and overall strategy effectiveness, enabling data-driven optimization of trading operations.
+
+## Key Features
+
+### Bot Performance Analysis (`/bot_performance`)
+
+#### 1. Data Source Selection
+- Load performance data from multiple sources (databases, checkpoints)
+- Support for real-time and historical data
+- Data validation and integrity checks
+- ETL (Extract, Transform, Load) capabilities
+
+#### 2. Performance Overview
+- Summary statistics across all trading activities
+- Key performance indicators (KPIs) dashboard
+- Profit/Loss aggregation by time period
+- Win rate and risk-adjusted returns
+
+#### 3. Global Results Analysis
+- Portfolio-wide performance metrics
+- Cross-strategy performance comparison
+- Asset allocation effectiveness
+- Market exposure analysis
+
+#### 4. Execution Analysis
+- Trade-by-trade breakdown
+- Slippage and execution quality metrics
+- Order fill rate analysis
+- Timing and market impact assessment
+
+#### 5. Data Export
+- Comprehensive reporting capabilities
+- Multiple export formats (CSV, JSON, Excel)
+- Customizable report templates
+- Automated report generation
+
+## User Flow
+
+1. **Data Loading**
+   - User selects data source (checkpoint, database)
+   - System loads and validates performance data
+   - ETL processes clean and prepare data
+   - Initial overview displayed
+
+2. **Performance Review**
+   - User examines summary metrics
+   - Drills down into specific time periods
+   - Analyzes individual strategy performance
+   - Identifies patterns and anomalies
+
+3. **Detailed Analysis**
+   - User investigates execution quality
+   - Reviews position-level details
+   - Analyzes risk metrics
+   - Compares against benchmarks
+
+4. **Reporting**
+   - User selects metrics of interest
+   - Customizes report parameters
+   - Exports data for external analysis
+   - Shares results with stakeholders
+
+## Technical Implementation Details
+
+### Performance Data Architecture
+```python
+# Data source structure
+PerformanceDataSource:
+  - executors_df: DataFrame of position data
+  - orders_df: DataFrame of order data
+  - trades_df: DataFrame of trade executions
+  - candles_df: Market data for context
+```
+
+### Key Metrics Calculated
+- **Returns**: Absolute, percentage, risk-adjusted
+- **Risk Metrics**: Sharpe ratio, maximum drawdown, VaR
+- **Execution Metrics**: Fill rate, slippage, spread capture
+- **Volume Metrics**: Turnover, market share, liquidity provision
+
+### Visualization Components
+- Time series charts for P&L evolution
+- Heatmaps for strategy correlation
+- Distribution plots for returns analysis
+- Scatter plots for risk/return profiles
+
+## Component Dependencies
+
+### Internal Dependencies
+- `backend.utils.performance_data_source`: Core data management
+- `frontend.visualization.bot_performance`: Performance charts
+- `frontend.visualization.performance_etl`: Data processing
+- `frontend.st_utils`: Streamlit utilities
+
+### External Dependencies
+- `pandas`: Data manipulation and analysis
+- `numpy`: Statistical calculations
+- `plotly`: Interactive visualizations
+- `streamlit`: Web interface framework
+
+### Data Sources
+- Hummingbot checkpoint files
+- SQLite performance databases
+- Real-time bot data feeds
+- Historical market data
+
+## State Management Approach
+
+### Session State Variables
+- `selected_checkpoint`: Active data source
+- `performance_data`: Loaded performance data
+- `filter_params`: Applied filters
+- `chart_settings`: Visualization preferences
+- `export_config`: Report settings
+
+### Caching Strategy
+- `@st.cache_data`: For expensive calculations
+- `@st.cache_resource`: For data source objects
+- Incremental updates for real-time data
+- Memory-efficient data structures
+
+### Data Processing Pipeline
+1. Raw data ingestion
+2. Data cleaning and validation
+3. Metric calculation
+4. Aggregation and grouping
+5. Visualization preparation
+
+## Best Practices
+
+1. **Data Quality**
+   - Validate data completeness
+   - Handle missing values appropriately
+   - Check for data anomalies
+   - Maintain data lineage
+
+2. **Performance Optimization**
+   - Use efficient data structures
+   - Implement lazy loading
+   - Cache computed metrics
+   - Optimize query patterns
+
+3. **Visualization Design**
+   - Choose appropriate chart types
+   - Maintain consistent color schemes
+   - Provide interactive elements
+   - Include context and annotations
+
+4. **User Experience**
+   - Progressive disclosure of complexity
+   - Intuitive navigation
+   - Responsive design
+   - Export flexibility
+
+## Performance Metrics Reference
+
+### Profitability Metrics
+- **Net P&L**: Total profit/loss after fees
+- **Return on Investment (ROI)**: Percentage return on capital
+- **Profit Factor**: Gross profit / Gross loss
+- **Average Trade P&L**: Mean profit per trade
+
+### Risk Metrics
+- **Maximum Drawdown**: Largest peak-to-trough decline
+- **Sharpe Ratio**: Risk-adjusted returns
+- **Sortino Ratio**: Downside risk-adjusted returns
+- **Value at Risk (VaR)**: Potential loss at confidence level
+
+### Execution Metrics
+- **Fill Rate**: Percentage of orders filled
+- **Average Slippage**: Difference between expected and actual price
+- **Spread Capture**: Percentage of spread captured
+- **Order Latency**: Time from signal to execution
+
+### Activity Metrics
+- **Trade Frequency**: Number of trades per period
+- **Average Position Duration**: Time positions are held
+- **Inventory Turnover**: How often inventory cycles
+- **Market Participation**: Percentage of market volume
+
+## Advanced Analysis Features
+
+### Performance Attribution
+- Breakdown returns by strategy component
+- Identify profit drivers
+- Analyze cost contributors
+- Market condition impact
+
+### Risk Analysis
+- Stress testing scenarios
+- Correlation analysis
+- Portfolio optimization suggestions
+- Risk limit monitoring
+
+### Comparative Analysis
+- Strategy comparison
+- Benchmark tracking
+- Peer performance analysis
+- Historical performance trends
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Data Loading Failures**
+   - Verify file paths and permissions
+   - Check data format compatibility
+   - Ensure sufficient memory
+   - Validate checkpoint integrity
+
+2. **Calculation Errors**
+   - Review data quality
+   - Check for edge cases
+   - Verify formula implementations
+   - Handle division by zero
+
+3. **Visualization Problems**
+   - Reduce data points for performance
+   - Check browser compatibility
+   - Clear cache if needed
+   - Verify data ranges
+
+### Performance Tips
+- Filter data before processing
+- Use appropriate aggregation levels
+- Leverage caching effectively
+- Optimize chart rendering

pages/performance/bot_performance/README.md

@@ -1,4 +1,4 @@
-This page helps you analize database files of several Hummingbot strategies and measure performance.
+This page helps you analyze database files of several Hummingbot strategies and measure performance.
 
 #### Support