From f9603fddd319843ae6ffeadaeca9471ac3edf1d5 Mon Sep 17 00:00:00 2001 From: mindesbunister Date: Wed, 23 Jul 2025 10:37:10 +0200 Subject: [PATCH] docs: Comprehensive documentation update with multi-timeframe lessons - Updated README.md with automation features and Docker troubleshooting - Enhanced copilot-instructions.md with multi-timeframe patterns and Docker workflows - Created DEVELOPMENT_GUIDE.md with comprehensive implementation patterns - Added troubleshooting section for volume mount issues - Documented fresh implementation approach vs file editing - Included performance optimization tips and future roadmap - Added testing strategies and common pitfall solutions Key knowledge preserved: - Multi-timeframe UI patterns and state management - Docker Compose v2 syntax and volume mount troubleshooting - Fresh file creation approach for problematic edits - Complete automation page implementation examples --- .github/copilot-instructions.instructions.md | 116 +++++++ DEVELOPMENT_GUIDE.md | 348 +++++++++++++++++++ README.md | 63 +++- prisma/prisma/dev.db | Bin 831488 -> 843776 bytes 4 files changed, 526 insertions(+), 1 deletion(-) create mode 100644 DEVELOPMENT_GUIDE.md diff --git a/.github/copilot-instructions.instructions.md b/.github/copilot-instructions.instructions.md index e125e13..22de578 100644 --- a/.github/copilot-instructions.instructions.md +++ b/.github/copilot-instructions.instructions.md @@ -55,6 +55,58 @@ npm run docker:exec # Shell access for debugging inside container - **Development**: External port `9001` โ†’ Internal port `3000` (http://localhost:9001) - **Production**: External port `9000` โ†’ Internal port `3000` (http://localhost:9000) +### Docker Volume Mount Troubleshooting +**Common Issue**: File edits not reflecting in container due to volume mount sync issues. + +**Solutions:** +1. **Fresh Implementation Approach**: When modifying existing files fails, create new files (e.g., `page-v2.js`) instead of editing corrupted files +2. **Container Restart**: `docker compose -f docker-compose.dev.yml restart app` +3. **Full Rebuild**: `docker compose -f docker-compose.dev.yml down && docker compose -f docker-compose.dev.yml up --build` +4. **Manual Copy**: Use `docker cp` to copy files directly into container for immediate testing +5. **Avoid sed/awk**: Direct text manipulation commands often corrupt JSX syntax - prefer file replacement + +**Volume Mount Verification:** +```bash +# Test volume mount sync +echo "test-$(date)" > test-volume-mount.txt +docker compose -f docker-compose.dev.yml exec app cat test-volume-mount.txt +``` + +### Multi-Timeframe Feature Copy Pattern +When copying multi-timeframe functionality between pages: + +**Step 1: Identify Source Implementation** +```bash +# Search for existing timeframe patterns +grep -r "timeframes.*=.*\[" app/ --include="*.js" --include="*.jsx" +grep -r "selectedTimeframes" app/ --include="*.js" --include="*.jsx" +``` + +**Step 2: Copy Core State Management** +```javascript +// Always include these state hooks +const [selectedTimeframes, setSelectedTimeframes] = useState(['1h', '4h']); +const [balance, setBalance] = useState({ balance: 0, collateral: 0 }); + +// Essential toggle function +const toggleTimeframe = (tf) => { + setSelectedTimeframes(prev => + prev.includes(tf) ? prev.filter(t => t !== tf) : [...prev, tf] + ); +}; +``` + +**Step 3: Copy UI Components** +- Timeframe checkbox grid +- Preset buttons (Scalping, Day Trading, Swing Trading) +- Auto-sizing position calculator +- Formatted balance display + +**Step 4: Avoid Docker Issues** +- Create new file instead of editing existing if volume mount issues persist +- Use fresh filename like `page-v2.js` or `automation-v2/page.js` +- Test in container before committing + ### API Route Structure All core functionality exposed via Next.js API routes: ```typescript @@ -105,6 +157,70 @@ const LAYOUT_URLS = { - `components/Dashboard.tsx` - Main trading dashboard with real Drift positions - `components/AdvancedTradingPanel.tsx` - Drift Protocol trading interface +### Page Structure & Multi-Timeframe Implementation +- `app/analysis/page.js` - Original analysis page with multi-timeframe functionality +- `app/automation/page.js` - Original automation page (legacy, may have issues) +- `app/automation-v2/page.js` - **NEW**: Clean automation page with full multi-timeframe support +- `app/automation/page-v2.js` - Alternative implementation, same functionality as automation-v2 + +**Multi-Timeframe Architecture Pattern:** +```javascript +// Standard timeframes array - use this exact format +const timeframes = ['5m', '15m', '30m', '1h', '2h', '4h', '1d']; + +// State management for multi-timeframe selection +const [selectedTimeframes, setSelectedTimeframes] = useState(['1h', '4h']); + +// Toggle function with proper array handling +const toggleTimeframe = (tf) => { + setSelectedTimeframes(prev => + prev.includes(tf) + ? prev.filter(t => t !== tf) // Remove if selected + : [...prev, tf] // Add if not selected + ); +}; + +// Preset configurations for trading styles +const presets = { + scalping: ['5m', '15m', '1h'], + day: ['1h', '4h', '1d'], + swing: ['4h', '1d'] +}; +``` + +**UI Pattern for Timeframe Selection:** +```jsx +// Checkbox grid layout with visual feedback +
+ {timeframes.map(tf => ( + + ))} +
+ +// Preset buttons for quick selection +
+ {Object.entries(presets).map(([name, tfs]) => ( + + ))} +
+``` + ## Environment Variables ```bash # AI Analysis (Required) diff --git a/DEVELOPMENT_GUIDE.md b/DEVELOPMENT_GUIDE.md new file mode 100644 index 0000000..00b9fb5 --- /dev/null +++ b/DEVELOPMENT_GUIDE.md @@ -0,0 +1,348 @@ +# ๐Ÿ› ๏ธ Development Guide: Multi-Timeframe Trading Bot + +## ๐Ÿš€ Quick Reference for Future Development + +This guide contains lessons learned and best practices from implementing the multi-timeframe automation functionality. Use this to accelerate future development and avoid common pitfalls. + +## ๐ŸŽฏ Multi-Timeframe Implementation Pattern + +### Core Architecture +```javascript +// Standard timeframes configuration +const timeframes = ['5m', '15m', '30m', '1h', '2h', '4h', '1d']; + +// State management +const [selectedTimeframes, setSelectedTimeframes] = useState(['1h', '4h']); +const [balance, setBalance] = useState({ balance: 0, collateral: 0 }); + +// Toggle function - EXACT implementation required +const toggleTimeframe = (tf) => { + setSelectedTimeframes(prev => + prev.includes(tf) + ? prev.filter(t => t !== tf) // Remove if selected + : [...prev, tf] // Add if not selected + ); +}; + +// Preset configurations +const presets = { + scalping: ['5m', '15m', '1h'], + day: ['1h', '4h', '1d'], + swing: ['4h', '1d'] +}; +``` + +### UI Components Pattern +```jsx +// Timeframe checkbox grid +
+ {timeframes.map(tf => ( + + ))} +
+ +// Preset buttons +
+ {Object.entries(presets).map(([name, tfs]) => ( + + ))} +
+ +// Position sizing with balance integration + +``` + +## ๐Ÿณ Docker Development Best Practices + +### Essential Commands (Docker Compose v2) +```bash +# Development environment (ALWAYS use for active development) +npm run docker:dev # Port 9001:3000 with hot reload +docker compose -f docker-compose.dev.yml up --build + +# Production environment +npm run docker:up # Port 9000:3000 optimized +docker compose -f docker-compose.prod.yml up --build + +# Debugging and maintenance +npm run docker:logs # View container logs +npm run docker:exec # Shell access to container +docker compose -f docker-compose.dev.yml restart app # Quick restart +``` + +### Volume Mount Troubleshooting + +**Problem**: File changes not reflecting in running container + +**Root Cause**: Docker volume mount synchronization issues, especially on Linux systems + +**Solutions (in order of preference)**: + +1. **Fresh Implementation Approach** (RECOMMENDED) + ```bash + # Instead of editing problematic files, create new ones + cp app/automation/page.js app/automation/page-v2.js + # OR create entirely new directory + mkdir app/automation-v2 + # Edit the new file instead + ``` + +2. **Container Restart** + ```bash + docker compose -f docker-compose.dev.yml restart app + ``` + +3. **Full Rebuild** + ```bash + docker compose -f docker-compose.dev.yml down + docker compose -f docker-compose.dev.yml up --build + ``` + +4. **Volume Mount Verification** + ```bash + # Test if volume mount is working + echo "test-$(date)" > test-volume-mount.txt + docker compose -f docker-compose.dev.yml exec app cat test-volume-mount.txt + # Should show the same timestamp + ``` + +5. **Manual File Copy** (for immediate testing) + ```bash + docker cp ./app/automation/page.js trader_dev:/app/app/automation/page.js + ``` + +### Text Editing Pitfalls + +**NEVER use sed/awk for JSX files** - They often corrupt the syntax. Examples of problematic approaches: +```bash +# โŒ DON'T DO THIS - Often corrupts JSX +sed -i 's/old_pattern/new_pattern/' app/automation/page.js + +# โŒ DON'T DO THIS - Breaks React syntax +awk 'pattern {action}' file.js > newfile.js +``` + +**โœ… PREFERRED approaches**: +1. Create new files instead of editing +2. Use proper editing tools that understand JSX +3. Manual copy/paste for small changes +4. Use the `replace_string_in_file` tool with proper context + +## ๐Ÿ“ File Organization Strategy + +### Current Page Structure +``` +app/ +โ”œโ”€โ”€ analysis/page.js # โœ… Original analysis with multi-timeframe +โ”œโ”€โ”€ automation/ +โ”‚ โ”œโ”€โ”€ page.js # โŒ Legacy, may have corruption issues +โ”‚ โ””โ”€โ”€ page-v2.js # โœ… Clean backup implementation +โ”œโ”€โ”€ automation-v2/ +โ”‚ โ””โ”€โ”€ page.js # โœ… NEW: Current working automation +โ””โ”€โ”€ ... +``` + +### Naming Conventions for New Features +- **Primary Implementation**: Use descriptive directory names (`automation-v2/`) +- **Backup/Alternative**: Add `-v2`, `-clean`, `-working` suffixes +- **Test Files**: Prefix with `test-` or put in `/test/` directory +- **Backup Files**: Add `.backup`, `.working-backup` extensions + +## ๐Ÿ” Feature Copying Workflow + +When copying functionality between pages (like analysis โ†’ automation): + +### Step 1: Research Existing Implementation +```bash +# Find timeframe-related code +grep -r "timeframes.*=.*\[" app/ --include="*.js" --include="*.jsx" +grep -r "selectedTimeframes" app/ --include="*.js" --include="*.jsx" +grep -r "toggleTimeframe" app/ --include="*.js" --include="*.jsx" +``` + +### Step 2: Create Clean Target File +```bash +# DON'T modify existing problematic files +# CREATE new clean implementation +cp app/analysis/page.js app/automation-v2/page.js +# OR start completely fresh +``` + +### Step 3: Copy Core Components +Required elements to copy: +- [ ] `timeframes` array definition +- [ ] `selectedTimeframes` state management +- [ ] `toggleTimeframe` function +- [ ] Timeframe checkbox grid UI +- [ ] Preset buttons (Scalping, Day Trading, Swing) +- [ ] Balance integration and formatting +- [ ] Position sizing calculations + +### Step 4: Test in Container +```bash +# Ensure container sees changes +npm run docker:dev +# Access http://localhost:9001/automation-v2 +# Verify all functionality works +``` + +### Step 5: Commit Clean Implementation +```bash +git add . +git commit -m "feat: Add automation V2 with multi-timeframe support" +git push +``` + +## ๐Ÿงช Testing Strategy + +### Functional Testing Checklist +- [ ] Timeframe checkboxes toggle correctly +- [ ] Preset buttons select correct timeframes +- [ ] Balance displays with proper formatting (2 decimal places) +- [ ] Position sizing calculates correctly +- [ ] Selected timeframes persist during page interaction +- [ ] Visual feedback shows selected state +- [ ] All 7 timeframes available (5m, 15m, 30m, 1h, 2h, 4h, 1d) + +### Docker Testing +```bash +# Test volume mount functionality +echo "test-$(date)" > test-volume-mount.txt +docker compose -f docker-compose.dev.yml exec app cat test-volume-mount.txt + +# Test hot reload +# Make a small change to a file and verify it reflects in browser + +# Test container logs +npm run docker:logs | grep -i error +``` + +## ๐Ÿšจ Common Pitfalls & Solutions + +### Issue: "selectedTimeframes is not defined" +**Cause**: State hook not properly imported or defined +**Solution**: +```javascript +import { useState } from 'react'; +const [selectedTimeframes, setSelectedTimeframes] = useState(['1h', '4h']); +``` + +### Issue: Checkboxes not showing selected state +**Cause**: Missing `.includes()` check in className +**Solution**: +```javascript +className={`... ${selectedTimeframes.includes(tf) ? 'selected-styles' : 'default-styles'}`} +``` + +### Issue: Balance showing as NaN or undefined +**Cause**: Balance not properly fetched or formatted +**Solution**: +```javascript +const [balance, setBalance] = useState({ balance: 0, collateral: 0 }); +// Format with: parseFloat(balance.balance).toFixed(2) +``` + +### Issue: File changes not reflecting in container +**Cause**: Docker volume mount sync issues +**Solution**: Use fresh implementation approach (create new files) + +### Issue: JSX syntax errors after text manipulation +**Cause**: sed/awk corruption of JSX syntax +**Solution**: Start with clean file, avoid text manipulation tools + +## ๐ŸŽฏ Performance Optimization + +### Multi-Timeframe Rendering +```javascript +// Efficient timeframe rendering with React.memo for large lists +const TimeframeButton = React.memo(({ tf, isSelected, onToggle }) => ( + +)); + +// Use in parent component +{timeframes.map(tf => ( + +))} +``` + +### Balance Updates +```javascript +// Throttle balance updates to avoid excessive API calls +useEffect(() => { + const fetchBalance = async () => { + try { + const response = await fetch('/api/balance'); + const data = await response.json(); + setBalance(data); + } catch (error) { + console.error('Balance fetch failed:', error); + } + }; + + fetchBalance(); + const interval = setInterval(fetchBalance, 30000); // Every 30 seconds + return () => clearInterval(interval); +}, []); +``` + +## ๐Ÿ“Š Future Development Roadmap + +### Immediate Improvements +- [ ] Add timeframe-specific position sizing recommendations +- [ ] Implement timeframe conflict detection (opposing signals) +- [ ] Add saved timeframe combinations (custom presets) +- [ ] Enhance balance integration with real-time updates + +### Advanced Features +- [ ] Multi-symbol automation across timeframes +- [ ] Automated position sizing based on volatility +- [ ] Cross-timeframe correlation analysis +- [ ] Risk management integration per timeframe + +### Code Quality +- [ ] TypeScript migration for automation pages +- [ ] Unit tests for timeframe logic +- [ ] Integration tests for Docker workflows +- [ ] Performance monitoring for multi-timeframe operations + +--- + +**Key Takeaway**: When in doubt, create new files instead of editing problematic ones. Docker volume mount issues are easier to solve with fresh implementations than complex debugging. + +**Success Pattern**: Analysis page โ†’ Clean automation-v2 implementation โ†’ Working multi-timeframe functionality diff --git a/README.md b/README.md index 43d5d5e..aebf80a 100644 --- a/README.md +++ b/README.md @@ -30,6 +30,14 @@ A professional-grade Next.js trading dashboard with AI-powered chart analysis, d - **Risk/Reward Ratios** with specific R:R calculations - **Confirmation Triggers** - Exact signals to wait for before entry +### ๐Ÿค– **Automated Trading Features** +- **Multi-Timeframe Automation** - Select 1-8 timeframes for comprehensive strategy coverage +- **Trading Style Presets** - Scalping (5m,15m,1h), Day Trading (1h,4h,1d), Swing (4h,1d) +- **Automatic Position Sizing** - Balance-based calculations with leverage recommendations +- **Real-Time Balance Integration** - Live wallet display with percentage-based position sizing +- **Risk Management** - Timeframe-specific leverage and position size recommendations +- **Clean UI/UX** - Checkbox-based timeframe selection with visual feedback + ### ๐Ÿ–ผ๏ธ **Enhanced Screenshot Service** - **Dual-Session Capture** - Parallel AI and DIY layout screenshots - **Docker Optimized** - Full CPU utilization for faster processing @@ -120,6 +128,39 @@ The system includes optimized Docker configurations: 3. **View Results** with consensus, divergences, and individual timeframe setups +### Multi-Timeframe Automation (/automation-v2) + +1. **Access Automation**: Navigate to `/automation-v2` for the latest automation interface +2. **Select Timeframes**: Use checkboxes to select 1-8 timeframes + - Individual selection: Click any timeframe checkbox + - Quick presets: Scalping, Day Trading, Swing Trading buttons +3. **Position Sizing**: + - View real-time wallet balance + - Select position percentage (1%, 5%, 10%, 25%, 50%) + - Automatic leverage calculations based on timeframe +4. **Execute**: Run automation across all selected timeframes simultaneously + +### Docker Development Workflow + +```bash +# Start development environment +npm run docker:dev # Runs on http://localhost:9001 + +# View logs for debugging +npm run docker:logs + +# Access container shell for troubleshooting +npm run docker:exec + +# Test volume mount sync (if files not updating) +echo "test-$(date)" > test-volume-mount.txt +docker compose -f docker-compose.dev.yml exec app cat test-volume-mount.txt + +# Full rebuild if issues persist +docker compose -f docker-compose.dev.yml down +docker compose -f docker-compose.dev.yml up --build +``` + ### API Usage ```bash @@ -180,7 +221,13 @@ node test-enhanced-screenshot.js ``` trading_bot_v3/ โ”œโ”€โ”€ app/ # Next.js app router -โ”‚ โ”œโ”€โ”€ api/enhanced-screenshot/ # Screenshot & AI analysis API +โ”‚ โ”œโ”€โ”€ analysis/ # Multi-timeframe analysis page +โ”‚ โ”œโ”€โ”€ automation/ # Trading automation pages +โ”‚ โ”‚ โ”œโ”€โ”€ page.js # Original automation (legacy) +โ”‚ โ”‚ โ””โ”€โ”€ page-v2.js # Clean automation implementation +โ”‚ โ”œโ”€โ”€ automation-v2/ # NEW: Multi-timeframe automation +โ”‚ โ”‚ โ””โ”€โ”€ page.js # Full automation with timeframe support +โ”‚ โ”œโ”€โ”€ api/enhanced-screenshot/ # Screenshot & AI analysis API โ”‚ โ”œโ”€โ”€ globals.css # Global styles โ”‚ โ”œโ”€โ”€ layout.tsx # Root layout โ”‚ โ””โ”€โ”€ page.tsx # Main dashboard @@ -212,6 +259,15 @@ node test-enhanced-screenshot.js # Test Docker setup docker compose up --build + +# Test automation features +curl -X POST http://localhost:9001/api/automation \ + -H "Content-Type: application/json" \ + -d '{ + "symbol": "BTCUSD", + "timeframes": ["1h", "4h", "1d"], + "positionSize": 10 + }' ``` ### Expected Test Output @@ -221,6 +277,11 @@ docker compose up --build โœ… API endpoint available ๐ŸŽฏ SUCCESS: Both AI and DIY layouts captured successfully! ๐Ÿ“Š Test Summary: 100% success rate + +๐Ÿค– Testing Multi-Timeframe Automation +โœ… Timeframe selection working +โœ… Position sizing calculations correct +โœ… Balance integration successful ``` ## ๐ŸŽฏ Features in Detail diff --git a/prisma/prisma/dev.db b/prisma/prisma/dev.db index 4c7b63708612d8e1ae6214a66d3833aa595cfa51..b9fd53c3f8ee95ddd4c9e756c901625e76530af9 100644 GIT binary patch delta 1245 zcmZvbZA=_R7{_;JckgEJ7J66VNO@f#RMWz-d)vL^j*z25i>;*8Kx-&ej+eW#*E={~ z3rK}K5-AZI8Y2(-LHb2)Y}yiu-I$n2OrsyvhM1V9#I!Wk_|_MVUyNwu98GH_eE9z} zlmG0@GrxIueAP9+q|RjVjSRzFJtO&1V?6Lt0KMC?g|v|^Z;2VHKc_0fJZW3B%X^8K zc-E5bFUrYJ_$=9QBaAXQo#z=iKZdr!H67)`{BaacU8{*aS65ptozVL`B@f6t3JHI{ z^CFtl)^5FE%K{<>3i;`SLj2|1(6y8b~ zd>waE|0-TW{mXdqWMUdoVJeo2qvEMdRAwq-B&LN#A=`!TfO$c#;UjmOZhMJkl2q4UY7kP?$@P;;y!!8l|z8jJ5XYaBr)7gt_=Aj%fV@ z!!%Zt@j$G=nO)g#RXCkyr}o%MCKhw7`9&SX2)=<6Q7yv)6X<-EA_ zA?Aw2%NsCn`j$z|msqdY3HCp5n#m<=&N9`=uQKZ#`yTm^%K?s-q5--|^o>QqVqHu!B;t0B<)b<3g(*n@ ze3;?GwC4l7{N~np={lVE$`kDy;B59EfUQGZ1*zUtjx;z^BsRmTptt~mbS@2~E4Ts1 zCar`<`LpaHX#RwCz(Kd!1~=a~Wj<`fg&)`>P&p(@AdL_QES)puBu6~FK1}QoI3?!5 zQkd|@{UK6-q32ib0GvBcXs=CMd8jKE{ctiuvXj%(P#Gny#_xBz@6k?|+8~$tRJU)J W>fGgZuOo2%4?%Q-wuU=85&0KCU5Eq# delta 281 zcmZoTVBGM)Xo56r2m=Gd>4^&Vj3JE)TN4h&Am-TK)Wg}N%$&{aIh}n2=XIdYY^LdNHgR&a2X5vB NVy^9ho4MEj0RSxuT4?|P