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
This commit is contained in:
mindesbunister
2025-07-23 10:37:10 +02:00
parent 730629a271
commit f9603fddd3
4 changed files with 526 additions and 1 deletions

View File

@@ -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
<div className="grid grid-cols-4 gap-2 mb-4">
{timeframes.map(tf => (
<button
key={tf}
onClick={() => toggleTimeframe(tf)}
className={`p-2 rounded border transition-all ${
selectedTimeframes.includes(tf)
? 'bg-blue-600 border-blue-500 text-white'
: 'bg-gray-700 border-gray-600 text-gray-300 hover:bg-gray-600'
}`}
>
{tf}
</button>
))}
</div>
// Preset buttons for quick selection
<div className="flex gap-2 mb-4">
{Object.entries(presets).map(([name, tfs]) => (
<button
key={name}
onClick={() => setSelectedTimeframes(tfs)}
className="px-3 py-1 bg-purple-600 hover:bg-purple-700 rounded text-sm"
>
{name.charAt(0).toUpperCase() + name.slice(1)}
</button>
))}
</div>
```
## Environment Variables
```bash
# AI Analysis (Required)

348
DEVELOPMENT_GUIDE.md Normal file
View File

@@ -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
<div className="grid grid-cols-4 gap-2 mb-4">
{timeframes.map(tf => (
<button
key={tf}
onClick={() => toggleTimeframe(tf)}
className={`p-2 rounded border transition-all ${
selectedTimeframes.includes(tf)
? 'bg-blue-600 border-blue-500 text-white'
: 'bg-gray-700 border-gray-600 text-gray-300 hover:bg-gray-600'
}`}
>
{tf}
</button>
))}
</div>
// Preset buttons
<div className="flex gap-2 mb-4">
{Object.entries(presets).map(([name, tfs]) => (
<button
key={name}
onClick={() => setSelectedTimeframes(tfs)}
className="px-3 py-1 bg-purple-600 hover:bg-purple-700 rounded text-sm"
>
{name.charAt(0).toUpperCase() + name.slice(1)}
</button>
))}
</div>
// Position sizing with balance integration
<select
value={positionPercentage}
onChange={(e) => setPositionPercentage(parseFloat(e.target.value))}
className="bg-gray-700 border border-gray-600 rounded px-3 py-2"
>
<option value={1}>1% (${(balance.balance * 0.01).toFixed(2)})</option>
<option value={5}>5% (${(balance.balance * 0.05).toFixed(2)})</option>
<option value={10}>10% (${(balance.balance * 0.10).toFixed(2)})</option>
<option value={25}>25% (${(balance.balance * 0.25).toFixed(2)})</option>
<option value={50}>50% (${(balance.balance * 0.50).toFixed(2)})</option>
</select>
```
## 🐳 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 }) => (
<button
onClick={() => onToggle(tf)}
className={`... ${isSelected ? 'selected' : 'default'}`}
>
{tf}
</button>
));
// Use in parent component
{timeframes.map(tf => (
<TimeframeButton
key={tf}
tf={tf}
isSelected={selectedTimeframes.includes(tf)}
onToggle={toggleTimeframe}
/>
))}
```
### 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

View File

@@ -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

Binary file not shown.