From 5bd2f97c2640519fbae76d1ed6f179768011b290 Mon Sep 17 00:00:00 2001 From: mindesbunister Date: Fri, 18 Jul 2025 10:28:02 +0200 Subject: [PATCH] docs: update copilot instructions with Docker container dev environment and Git workflow - Emphasize Docker container development as required environment - Add Docker Compose v2 usage with specific port mappings (9001:3000 dev, 9000:3000 prod) - Define Git branch strategy: development branch for active work, main for stable code - Include complete development workflow with Git commands - Clarify external/internal port configuration for both environments --- .github/copilot-instructions.md | 154 +++++++++++++++++++++++--------- 1 file changed, 113 insertions(+), 41 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 6cfac0e..8e33110 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -1,5 +1,3 @@ - - # AI-Powered Trading Bot Dashboard This is a Next.js 15 App Router application with TypeScript, Tailwind CSS, and API routes. It's a production-ready trading bot with AI analysis, automated screenshot capture, and real-time trading execution via Drift Protocol and Jupiter DEX. @@ -11,28 +9,43 @@ This is a Next.js 15 App Router application with TypeScript, Tailwind CSS, and A - **DIY Layout**: `vWVvjLhP` - Stochastic RSI (top), VWAP, OBV (bottom) - Parallel browser sessions for multi-layout capture in `lib/enhanced-screenshot.ts` - TradingView automation with session persistence in `lib/tradingview-automation.ts` +- Session data stored in `.tradingview-session/` volume mount to avoid captchas ### AI Analysis Pipeline - OpenAI GPT-4o mini for cost-effective chart analysis (~$0.006 per analysis) -- Multi-layout comparison and consensus detection +- Multi-layout comparison and consensus detection in `lib/ai-analysis.ts` - Professional trading setups with exact entry/exit levels and risk management - Layout-specific indicator analysis (RSI vs Stochastic RSI, MACD vs OBV) ### Trading Integration - **Drift Protocol**: Perpetual futures trading via `@drift-labs/sdk` - **Jupiter DEX**: Spot trading on Solana -- Position management and P&L tracking +- Position management and P&L tracking in `lib/drift-trading-final.ts` - Real-time account balance and collateral monitoring ## Critical Development Patterns -### Docker Environment -Use Docker for consistency: `npm run docker:dev` (port 9001) or `npm run docker:up` (port 9000) -- Multi-stage builds with browser automation optimizations -- Session persistence via volume mounts -- Chromium path: `/usr/bin/chromium` +### Docker Container Development (Required) +**All development happens inside Docker containers** using Docker Compose v2. Browser automation requires specific system dependencies that are only available in the containerized environment: + +```bash +# Development environment - Docker Compose v2 dev setup +npm run docker:dev # Port 9001:3000, hot reload, debug mode + +# Production environment +npm run docker:up # Port 9000:3000, optimized build + +# Debugging commands +npm run docker:logs # View container logs +npm run docker:exec # Shell access for debugging inside container +``` + +**Port Configuration:** +- **Development**: External port `9001` → Internal port `3000` (http://localhost:9001) +- **Production**: External port `9000` → Internal port `3000` (http://localhost:9000) ### API Route Structure +All core functionality exposed via Next.js API routes: ```typescript // Enhanced screenshot with progress tracking POST /api/enhanced-screenshot @@ -42,63 +55,122 @@ POST /api/enhanced-screenshot layouts: ["ai", "diy"], analyze: true } - // Returns: { screenshots, analysis, sessionId } + +// Drift trading endpoints +GET /api/balance # Account balance/collateral +POST /api/trading # Execute trades +GET /api/status # Trading status ``` ### Progress Tracking System -- `lib/progress-tracker.ts` manages real-time analysis progress +Real-time operation tracking for long-running tasks: +- `lib/progress-tracker.ts` manages EventEmitter-based progress - SessionId-based tracking for multi-step operations - Steps: init → auth → navigation → loading → capture → analysis +- Stream endpoint: `/api/progress/[sessionId]/stream` -### Timeframe Mapping -Critical: Always use minute values first to avoid TradingView confusion +### TradingView Automation Patterns +Critical timeframe handling to avoid TradingView confusion: ```typescript -'4h': ['240', '240m', '4h', '4H'] // 240 minutes FIRST, not "4h" +// ALWAYS use minute values first, then alternatives +'4h': ['240', '240m', '4h', '4H'] // 240 minutes FIRST '1h': ['60', '60m', '1h', '1H'] // 60 minutes FIRST +'15m': ['15', '15m'] +``` + +Layout URL mappings for direct navigation: +```typescript +const LAYOUT_URLS = { + 'ai': 'Z1TzpUrf', // RSI + EMAs + MACD + 'diy': 'vWVvjLhP' // Stochastic RSI + VWAP + OBV +} ``` ### Component Architecture +- `app/layout.js` - Root layout with gradient styling and navigation +- `components/Navigation.tsx` - Multi-page navigation system - `components/AIAnalysisPanel.tsx` - Multi-timeframe analysis interface - `components/Dashboard.tsx` - Main trading dashboard with real Drift positions - `components/AdvancedTradingPanel.tsx` - Drift Protocol trading interface -- Layout: `app/layout.js` with gradient styling and navigation ## Environment Variables ```bash -OPENAI_API_KEY= # Required for AI analysis -TRADINGVIEW_EMAIL= # Required for automation -TRADINGVIEW_PASSWORD= # Required for automation -SOLANA_RPC_URL= # Drift trading -DRIFT_PRIVATE_KEY= # Drift trading (base58 encoded) +# AI Analysis (Required) +OPENAI_API_KEY=sk-... # OpenAI API key for chart analysis + +# TradingView Automation (Required) +TRADINGVIEW_EMAIL= # TradingView account email +TRADINGVIEW_PASSWORD= # TradingView account password + +# Trading Integration (Optional) +SOLANA_RPC_URL=https://api.mainnet-beta.solana.com +DRIFT_PRIVATE_KEY= # Base58 encoded Solana private key +SOLANA_PRIVATE_KEY= # JSON array format for Jupiter DEX + +# Docker Environment Detection +DOCKER_ENV=true # Auto-set in containers +PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium ``` -## Build & Development Commands +## Testing & Debugging Workflow +Test files follow specific patterns - use them to validate changes: ```bash -# Development (recommended) -npm run docker:dev # Port 9001, hot reload -npm run docker:logs # View container logs -npm run docker:exec # Shell access +# Test dual-session screenshot capture +node test-enhanced-screenshot.js -# Production deployment -npm run docker:prod:up # Port 9000, optimized build +# Test Docker environment +./test-docker-comprehensive.sh -# Testing automation -node test-enhanced-screenshot.js # Test dual-session capture -./test-docker-comprehensive.sh # Full system test +# Test API endpoints directly +node test-analysis-api.js + +# Test Drift trading integration +node test-drift-trading.js ``` -## Code Style Guidelines -- Use `"use client"` for client components with state/effects -- Tailwind with gradient backgrounds and glassmorphism effects -- TypeScript interfaces for all trading parameters and API responses -- Error handling with detailed logging for browser automation -- Session persistence to avoid TradingView captchas +Browser automation debugging: +- Screenshots automatically saved to `screenshots/` with timestamps +- Debug screenshots: `takeDebugScreenshot('prefix')` +- Session persistence prevents repeated logins/captchas +- Use `npm run docker:logs` to view real-time automation logs + +## Code Style & Architecture Patterns +- **Client Components**: Use `"use client"` for state/effects, server components by default +- **Styling**: Tailwind with gradient backgrounds (`bg-gradient-to-br from-gray-900 via-blue-900 to-purple-900`) +- **Error Handling**: Detailed logging for browser automation with fallbacks +- **File Structure**: Mixed `.js`/`.tsx` - components in TypeScript, API routes in JavaScript +- **Database**: Prisma with SQLite (`DATABASE_URL=file:./prisma/dev.db`) ## Key Integration Points -- Session data: `.tradingview-session/` (volume mounted) -- Screenshots: `screenshots/` directory -- Progress tracking: EventEmitter-based real-time updates -- Database: Prisma with SQLite (file:./prisma/dev.db) +- **Session Persistence**: `.tradingview-session/` directory volume-mounted +- **Screenshots**: `screenshots/` directory for chart captures +- **Progress Tracking**: EventEmitter-based real-time updates via SSE +- **Multi-Stage Docker**: Development vs production builds with browser optimization +- **CAPTCHA Handling**: Manual CAPTCHA mode with X11 forwarding (`ALLOW_MANUAL_CAPTCHA=true`) -Generate code that follows these patterns and integrates seamlessly with the existing trading infrastructure. +## Development vs Production Modes +- **Development**: Port 9001:3000, hot reload, debug logging, headless: false option +- **Production**: Port 9000:3000, optimized build, minimal logging, always headless + +### Git Branch Strategy (Required) +**Primary development workflow:** +- **`development` branch**: Use for all active development and feature work +- **`main` branch**: Stable, production-ready code only +- **Workflow**: Develop on `development` → test thoroughly → merge to `main` when stable + +```bash +# Standard development workflow +git checkout development # Always start here +git pull origin development # Get latest changes +# Make your changes... +git add . && git commit -m "feat: description" +git push origin development + +# Only merge to main when features are stable and tested and you have asked the user to merge to main +git checkout main +git merge development # When ready for production +git push origin main +``` + +When working with this codebase, prioritize Docker consistency, understand the dual-session architecture, and leverage the comprehensive test suite to validate changes.