trading_bot_v3/.github/copilot-instructions.md

# GitHub Copilot Instructions for Trading Bot Development

## 🎯 Project Context & Architecture

This is an AI-powered trading automation system with advanced learning capabilities. When working on this codebase:

### Core System Components
1. **Superior Parallel Screenshot System** - 60% faster than sequential capture
2. **AI Learning System** - Adapts trading decisions based on outcomes  
3. **Orphaned Order Cleanup** - Automatic cleanup when positions close
4. **Position Monitoring** - Frequent checks with integrated cleanup triggers

### Critical File Relationships
```
app/api/automation/position-monitor/route.js → Monitors positions + triggers cleanup
lib/simplified-stop-loss-learner.js → AI learning core with pattern recognition
lib/superior-screenshot-service.ts → Parallel screenshot capture system
lib/enhanced-autonomous-risk-manager.js → Risk management with AI integration
```

## 🧠 AI Learning System Patterns

### Always Include These Functions in Learning Classes:
```javascript
async generateLearningReport() {
  // Return comprehensive learning status
  return {
    summary: { totalDecisions, systemConfidence, successRate },
    insights: { thresholds, confidenceLevel },
    recommendations: []
  };
}

async getSmartRecommendation(requestData) {
  // Analyze patterns and return AI recommendation
  const { distanceFromSL, symbol, marketConditions } = requestData;
  // Return: { action, confidence, reasoning }
}

async recordDecision(decisionData) {
  // Log decision for learning with unique ID
  const id = `decision_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
  // Store in database for pattern analysis
}

async assessDecisionOutcome(outcomeData) {
  // Update decision with actual result for learning
  // Calculate if decision was correct based on outcome
}
```

### Database Operations Best Practices:
```javascript
// ALWAYS provide unique IDs for Prisma records
await prisma.ai_learning_data.create({
  data: {
    id: `${prefix}_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`,
    // ... other fields
  }
});

// Use correct import path
const { getDB } = require('./db');  // NOT './database-util'
```

## 🔧 Error Handling Patterns

### Function Existence Checks:
```javascript
// Always check if functions exist before calling
if (typeof this.learner.generateLearningReport === 'function') {
  const report = await this.learner.generateLearningReport();
} else {
  // Fallback to alternative method
  const status = await this.learner.getLearningStatus();
}
```

### Comprehensive Try-Catch:
```javascript
try {
  const result = await aiFunction();
  return result;
} catch (error) {
  await this.log(`❌ AI function error: ${error.message}`);
  return fallbackResult(); // Always provide fallback
}
```

## 📊 Integration Patterns

### Position Monitor Integration:
```javascript
// When no position detected, check for orphaned orders
if (!result.hasPosition) {
  console.log('📋 No active positions detected - checking for orphaned orders...');
  
  try {
    const ordersResponse = await fetch(`${baseUrl}/api/drift/orders`);
    if (ordersResponse.ok) {
      const ordersData = await ordersResponse.json();
      if (ordersData.orders?.length > 0) {
        // Trigger cleanup
        const cleanupResponse = await fetch(`${baseUrl}/api/drift/cleanup-orders`, {
          method: 'POST'
        });
        // Handle cleanup result
      }
    }
  } catch (error) {
    // Handle error gracefully
  }
}
```

### Parallel Processing for Screenshots:
```javascript
// Use Promise.allSettled for parallel processing
const promises = timeframes.map(timeframe => 
  captureTimeframe(timeframe, symbol, layoutType)
);
const results = await Promise.allSettled(promises);

// Process results with error isolation
results.forEach((result, index) => {
  if (result.status === 'fulfilled') {
    // Handle success
  } else {
    // Handle individual failure without breaking others
  }
});
```

## 🎯 Performance Optimization Rules

### Screenshot Capture:
- Always use parallel processing for multiple timeframes
- Reuse browser sessions to avoid login/captcha
- Isolate errors so one failure doesn't break others
- Prefer `Promise.allSettled` over `Promise.all`

### Database Queries:
- Use indexed fields for frequent searches (symbol, createdAt)
- Batch operations when possible
- Include proper error handling for connection issues

### Container Optimization:
- Check syntax before deployment: `node -c filename.js`
- Use health checks for monitoring
- Implement graceful shutdown handling

## 🧪 Testing Requirements

### Always Include These Tests:
```javascript
// Test AI learning functions
const learner = new SimplifiedStopLossLearner();
const report = await learner.generateLearningReport();
console.log('Learning report:', report.summary);

// Test API endpoints
const response = await fetch('/api/automation/position-monitor');
const result = await response.json();
console.log('Position monitor working:', result.success);

// Test error scenarios
try {
  await riskyFunction();
} catch (error) {
  console.log('Error handling working:', error.message);
}
```

## 🎨 UI/UX Patterns

### Preset Configuration:
```javascript
// Frontend presets MUST match backend exactly
const TRADING_PRESETS = {
  scalp: ['5m', '15m', '30m'],    // NOT ['5m', '15m', '1h']
  day: ['1h', '2h'],              // NOT ['1h', '4h', '1d']  
  swing: ['4h', '1D'],
  extended: ['1m', '3m', '5m', '15m', '30m', '1h', '4h', '1D']
};
```

### Status Display:
```javascript
// Always provide detailed feedback
return {
  success: true,
  monitor: {
    hasPosition: false,
    orphanedOrderCleanup: {
      triggered: true,
      success: true,
      message: 'Cleaned up 2 orphaned orders',
      summary: { totalCanceled: 2 }
    }
  }
};
```

## 🔍 Debugging Strategies

### Container Issues:
```bash
# Check for syntax errors
find . -name "*.js" -exec node -c {} \;

# Monitor logs for patterns
docker logs trader_dev --since="1m" | grep -E "(Error|unhandled|crash)"

# Test specific components
node test-learning-system.js
```

### Integration Issues:
```bash
# Test API endpoints individually
curl -s http://localhost:9001/api/automation/position-monitor | jq .

# Verify database connectivity
node -e "const {getDB} = require('./lib/db'); getDB().then(() => console.log('DB OK'));"
```

## 🚨 Critical Anti-Patterns to Avoid

### ❌ Don't Do This:
```javascript
// Missing error handling
const report = await this.learner.generateLearningReport(); // Will crash if function missing

// Redundant polling
setInterval(checkOrders, 60000); // When position monitor already runs frequently

// Frontend/backend preset mismatch  
backend: ['5m', '15m', '1h']
frontend: ['5m', '15m', '30m'] // Will cause confusion

// Missing unique IDs
await prisma.create({ data: { symbol, timeframe } }); // Will fail validation
```

### ✅ Do This Instead:
```javascript
// Defensive programming
if (typeof this.learner.generateLearningReport === 'function') {
  try {
    const report = await this.learner.generateLearningReport();
  } catch (error) {
    await this.log(`Report generation failed: ${error.message}`);
  }
}

// Leverage existing infrastructure
// Add cleanup to existing position monitor instead of new polling

// Ensure consistency
const PRESETS = { scalp: ['5m', '15m', '30m'] }; // Same in frontend and backend

// Always provide unique IDs
const id = `${type}_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
```

## 🎯 Configuration Standards

### Environment Variables:
```javascript
// Always provide fallbacks
const apiKey = process.env.OPENAI_API_KEY || '';
if (!apiKey) {
  throw new Error('OPENAI_API_KEY is required');
}
```

### Next.js Configuration:
```typescript
// Use new format, not deprecated
const nextConfig: NextConfig = {
  serverExternalPackages: ['puppeteer-core'], // NOT experimental.serverComponentsExternalPackages
  transpilePackages: ['next-font'],
  typescript: { ignoreBuildErrors: true },
  eslint: { ignoreDuringBuilds: true }
};
```

## 📈 Enhancement Guidelines

When adding new features:

1. **Check Existing Infrastructure** - Can it be integrated vs creating new?
2. **Add Comprehensive Error Handling** - Assume functions may not exist
3. **Include Fallback Mechanisms** - System should work without AI/learning
4. **Test in Isolation** - Create test scripts for new components
5. **Document Integration Points** - How does it connect to existing systems?
6. **Maintain Consistency** - Frontend and backend must match exactly
7. **Use Defensive Programming** - Check before calling, handle gracefully

---

**Follow these patterns to maintain system stability and avoid the complex debugging issues that were resolved in this session.**