# Trading Bot v4 Documentation

**Comprehensive documentation for the Trading Bot v4 autonomous trading system.**

Last Updated: December 4, 2025

---

## 📂 Documentation Structure

### **[analysis/](analysis/)** - Performance Analysis & Optimization Studies
Performance analyses, blocked signals tracking, profit projections, and diagnostic results. Data-driven insights for system optimization.

### **[architecture/](architecture/)** - System Architecture & Design
Adaptive leverage system, ATR trailing stops, indicator version tracking, and position synchronization. Core technical design documentation.

### **[bugs/](bugs/)** - Bug Reports & Critical Fixes
CRITICAL_*.md and FIXES_*.md bug reports. Historical record of critical incidents and their resolutions.

### **[cluster/](cluster/)** - Distributed Computing & EPYC Cluster
EPYC cluster setup, distributed backtesting coordination, dual sweep configurations. Multi-server infrastructure documentation.

### **[deployments/](deployments/)** - Deployment Status & Verification
*_COMPLETE.md and DEPLOYMENT_*.md status files. Verification reports for major feature deployments.

### **[roadmaps/](roadmaps/)** - Strategic Planning & Roadmaps
All *ROADMAP*.md files. Long-term strategic planning for system enhancements across multiple dimensions.

### **[setup/](setup/)** - Setup Guides & Configuration
TradingView alert setup, n8n workflows, signal quality configuration, percentage sizing features.

### **[archived/](archived/)** - Historical Documentation
Obsolete verification checklists and documentation from previous development phases.

---

## 🚀 Quick Start

**New Developers:**
1. Read [TRADING_GOALS.md](TRADING_GOALS.md) - Understand financial objectives
2. Review [roadmaps/OPTIMIZATION_MASTER_ROADMAP.md](roadmaps/OPTIMIZATION_MASTER_ROADMAP.md) - Strategic vision
3. Check [setup/QUICK_SETUP_CARD.md](setup/QUICK_SETUP_CARD.md) - Quick configuration reference
4. Study [architecture/ADAPTIVE_LEVERAGE_SYSTEM.md](architecture/ADAPTIVE_LEVERAGE_SYSTEM.md) - Core risk management

**Debugging Issues:**
1. Search [bugs/](bugs/) directory for similar incidents
2. Review Common Pitfalls in `.github/copilot-instructions.md`
3. Check [deployments/](deployments/) for recent changes
4. Consult [analysis/DIAGNOSTIC_RESULTS_SUMMARY.md](analysis/DIAGNOSTIC_RESULTS_SUMMARY.md)

**Feature Development:**
1. Check [roadmaps/](roadmaps/) for planned enhancements
2. Review [architecture/](architecture/) for existing patterns
3. Read deployment verification docs in [deployments/](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](TRADING_GOALS.md) for complete financial roadmap ($106 → $100k+)

---

## 🔍 Finding Documentation

**By Topic:**
- **Performance Data:** [analysis/](analysis/)
- **System Design:** [architecture/](architecture/)
- **Bug History:** [bugs/](bugs/)
- **Infrastructure:** [cluster/](cluster/)
- **Feature Status:** [deployments/](deployments/)
- **Future Plans:** [roadmaps/](roadmaps/)
- **Setup Guides:** [setup/](setup/)

**By Date:**
- Most recent deployments in [deployments/](deployments/)
- Historical bugs in [bugs/](bugs/)
- Archived docs in [archived/](archived/)

**By File Type:**
- `*ROADMAP.md` → [roadmaps/](roadmaps/)
- `CRITICAL_*.md` → [bugs/](bugs/)
- `*_COMPLETE.md` → [deployments/](deployments/)
- `*_ANALYSIS.md` → [analysis/](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/](deployments/) - Update immediately after deployment
- **Weekly:** [roadmaps/](roadmaps/) - Review progress, update status
- **Monthly:** [analysis/](analysis/) - Performance review, optimization analysis
- **As-needed:** [bugs/](bugs/), [setup/](setup/), [architecture/](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/](deployments/)
4. Update roadmap status in [roadmaps/](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"
- Common Pitfalls, new ENV variables, configuration changes → Document immediately
- Bug fixes → Add to Common Pitfalls with full incident details

---

## 🔗 External References

- **Main Repository:** `/home/icke/traderv4/`
- **Configuration:** `.github/copilot-instructions.md` (6,400+ lines)
- **Environment Variables:** `.env` (482 lines)
- **Database Schema:** `prisma/schema.prisma`
- **Primary Code:** `app/api/trading/`, `lib/trading/`, `lib/drift/`

---

## 📞 Support

**For Issues:**
1. Check [bugs/](bugs/) for similar problems
2. Review Common Pitfalls in `.github/copilot-instructions.md`
3. Consult [deployments/](deployments/) for recent changes
4. Search git history: `git log --grep="keyword"`

**For Features:**
1. Check [roadmaps/](roadmaps/) for planned work
2. Review [architecture/](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".