📚 COMPREHENSIVE KNOWLEDGE DOCUMENTATION
ADVANCED SYSTEM KNOWLEDGE: - Superior parallel screenshot system (60% performance gain) - AI learning system architecture and decision flow - Orphaned order cleanup integration patterns - Critical technical fixes and troubleshooting guide - Database schema best practices - Memory leak prevention strategies - AI learning system patterns and functions - Error handling best practices for trading systems - Integration patterns for position monitoring - Performance optimization rules - UI/UX consistency requirements - Critical anti-patterns to avoid - Added links to new knowledge base documents - Comprehensive documentation structure - Development guides and best practices - Performance optimizations summary - 60% screenshot performance improvement techniques - AI learning system that adapts trading decisions - Container stability and crash prevention - Frontend-backend consistency requirements - Integration strategies for existing infrastructure This documentation preserves critical insights from complex debugging sessions and provides patterns for future development.
This commit is contained in:
mindesbunister
302
.github/copilot-instructions.md
vendored
Normal file
302
.github/copilot-instructions.md
vendored
Normal file
@@ -0,0 +1,302 @@
|
||||
# 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.**
|
||||
Reference in New Issue
Block a user