trading_bot_v4/docs

Trading Bot v4 Documentation

Comprehensive documentation for the Trading Bot v4 autonomous trading system.

Last Updated: December 4, 2025

---

📂 Documentation Structure

analysis/ - Performance Analysis & Optimization Studies

Performance analyses, blocked signals tracking, profit projections, and diagnostic results. Data-driven insights for system optimization.

architecture/ - System Architecture & Design

Adaptive leverage system, ATR trailing stops, indicator version tracking, and position synchronization. Core technical design documentation.

bugs/ - Bug Reports & Critical Fixes

CRITICAL_.md and FIXES_.md bug reports. Historical record of critical incidents and their resolutions.

cluster/ - Distributed Computing & EPYC Cluster

EPYC cluster setup, distributed backtesting coordination, dual sweep configurations. Multi-server infrastructure documentation.

deployments/ - Deployment Status & Verification

COMPLETE.md and DEPLOYMENT.md status files. Verification reports for major feature deployments.

roadmaps/ - Strategic Planning & Roadmaps

All ROADMAP.md files. Long-term strategic planning for system enhancements across multiple dimensions.

setup/ - Setup Guides & Configuration

TradingView alert setup, n8n workflows, signal quality configuration, percentage sizing features.

archived/ - Historical Documentation

Obsolete verification checklists and documentation from previous development phases.

---

🚀 Quick Start

New Developers:

1. Read TRADING_GOALS.md - Understand financial objectives
2. Review roadmaps/OPTIMIZATION_MASTER_ROADMAP.md - Strategic vision
3. Check setup/QUICK_SETUP_CARD.md - Quick configuration reference
4. Study architecture/ADAPTIVE_LEVERAGE_SYSTEM.md - Core risk management

Debugging Issues:

1. Search bugs/ directory for similar incidents
2. Review COMMON_PITFALLS.md for documented issues (72 pitfalls)
3. Check deployments/ for recent changes
4. Consult analysis/DIAGNOSTIC_RESULTS_SUMMARY.md

Feature Development:

1. Check roadmaps/ for planned enhancements
2. Review architecture/ for existing patterns
3. Read deployment verification docs in deployments/
4. Follow verification procedures before marking features "complete"

---

📊 Current System Status

Production Configuration (Dec 4, 2025):

• Capital: $540 USDC (100% health, zero debt)
• Quality Thresholds: LONG ≥90, SHORT ≥95
• Adaptive Leverage: 10x for high-quality (≥95), 5x for borderline (90-94)
• Indicator: v9 Money Line with MA Gap + Momentum SHORT Filter
• Position Sizing: SOL-PERP at 100% allocation, 5x leverage
• Runner System: TP1 closes 60%, TP2 activates trailing stop on 40% runner
• Smart Entry: Enabled (waits for 0.3% pullback confirmation)

See TRADING_GOALS.md for complete financial roadmap ($106 → $100k+)

---

🔍 Finding Documentation

By Topic:

• Performance Data: analysis/
• System Design: architecture/
• Bug History: bugs/
• Infrastructure: cluster/
• Feature Status: deployments/
• Future Plans: roadmaps/
• Setup Guides: setup/

By Date:

• Most recent deployments in deployments/
• Historical bugs in bugs/
• Archived docs in archived/

By File Type:

• *ROADMAP.md → roadmaps/
• CRITICAL_*.md → bugs/
• *_COMPLETE.md → deployments/
• *_ANALYSIS.md → analysis/

---

📝 Documentation Standards

File Naming Conventions:

• UPPERCASE_WITH_UNDERSCORES.md - Important permanent docs
• lowercase-with-dashes.md - Temporary or draft docs
• *_COMPLETE.md - Verified deployment status
• CRITICAL_*.md - Bug reports requiring immediate attention

Content Requirements:

• Date stamps: All docs must include creation/update dates
• Status indicators: Use emojis (✅ ❌ 🔄 ⏳ 🎯) for quick status scanning
• Code examples: Always include working code snippets for complex features
• Verification steps: Document how to verify feature is working
• Lessons learned: Include "Why This Matters" and "Lessons Learned" sections

Update Frequency:

• Real-time: deployments/ - Update immediately after deployment
• Weekly: roadmaps/ - Review progress, update status
• Monthly: analysis/ - Performance review, optimization analysis
• As-needed: bugs/, setup/, architecture/

---

🤝 Contributing

Before Committing:

1. Update relevant documentation in appropriate subdirectory
2. Add entry to .github/copilot-instructions.md if system behavior changes
3. Create deployment verification doc in deployments/
4. Update roadmap status in roadmaps/ if completing phase
5. Git commit with descriptive message (docs:, feat:, fix:, critical:)

Documentation Mandate:

• EVERY git commit requires documentation update - Code without docs = incomplete work
• See .github/copilot-instructions.md "DOCUMENTATION + GIT COMMIT: INSEPARABLE WORKFLOW"
• ENV variables, configuration changes → Document in copilot-instructions.md
• Bug fixes → Add to docs/COMMON_PITFALLS.md with full incident details

---

🔗 External References

• Main Repository: /home/icke/traderv4/
• Configuration: .github/copilot-instructions.md (3,600+ lines)
• Common Pitfalls: docs/COMMON_PITFALLS.md (72 documented issues)
• Environment Variables: .env (482 lines)
• Database Schema: prisma/schema.prisma
• Primary Code: app/api/trading/, lib/trading/, lib/drift/

---

📞 Support

For Issues:

1. Check COMMON_PITFALLS.md for documented issues (72 pitfalls)
2. Search bugs/ for similar problems
3. Consult deployments/ for recent changes
4. Search git history: git log --grep="keyword"

For Features:

1. Check roadmaps/ for planned work
2. Review architecture/ for existing patterns
3. Study similar implementations in git history

Remember: This is a real money trading system - every change affects financial outcomes. Always verify thoroughly before declaring anything "working" or "fixed".