trading_bot_v4/docs/architecture

System Architecture & Design

Core technical design documentation for Trading Bot v4 autonomous trading system.

This directory contains architectural decisions, system design patterns, and technical specifications for major system components.

---

🏗️ Key Architecture Documents

Adaptive Leverage System

• ADAPTIVE_LEVERAGE_SYSTEM.md - Complete implementation guide
  • Quality-based leverage tiers (10x for ≥95, 5x for 90-94)
  • Direction-specific thresholds (LONG ≥95, SHORT ≥90)
  • Settings UI with real-time collateral display
  • Risk-adjusted position sizing based on signal confidence
  • Status: ✅ ACTIVE in production (Dec 1, 2025)

ATR Trailing Stop System

• ATR_TRAILING_STOP_FIX.md - Phase 7.3 adaptive trailing enhancement
  • Real-time 1-minute ADX monitoring (not static entry ADX)
  • Dynamic trail multipliers: base 1.5× + ADX strength tier + acceleration bonus
  • ADX acceleration (+7 points) → 1.3× multiplier
  • Profit acceleration (>2%) → additional 1.3× multiplier
  • Combined max: 3.16× multiplier for strong trending moves
  • Status: ✅ DEPLOYED (Nov 27, 2025)

Indicator Version Tracking

• INDICATOR_VERSION_TRACKING.md - TradingView strategy versioning
  • v9: Money Line with MA Gap + Momentum SHORT Filter (PRODUCTION)
  • v8: Money Line Sticky Trend (ARCHIVED - 57.1% WR baseline)
  • Historical versions (v5-v7) for comparison
  • Database field tracking for performance analysis
  • Purpose: A/B testing and strategy evolution

Position Synchronization

• POSITION_SYNC_QUICK_REF.md - Position Manager sync procedures
  • Startup validation (orphan detection)
  • External closure handling
  • Ghost position cleanup
  • Database-first state management
  • Critical for: System restarts, container crashes

---

🎯 Design Principles

1. Database as Source of Truth

• All state-changing operations write to database FIRST
• In-memory state (Position Manager) is derived from database
• Container restarts restore state from database
• External closures update database before removing from memory

2. Dual-Layer Redundancy

• Layer 1: On-chain orders (Drift Protocol TP/SL limit orders)
• Layer 2: Software monitoring (Position Manager every 2 seconds)
• If on-chain orders fail, Position Manager executes via market orders
• Both layers track to same database for complete history

3. Singleton Pattern Everywhere

// CORRECT: Use getter functions
const driftService = await initializeDriftService()
const positionManager = await getInitializedPositionManager()
const prisma = getPrismaClient()

// WRONG: Never create multiple instances
const driftService = new DriftService()  // ❌

4. Adaptive Systems Over Static Parameters

• ATR-based TP/SL: Adapts to market volatility automatically
• Adaptive Leverage: Scales risk with signal quality
• ADX-based Trailing: Widens trail during trend acceleration
• Smart Entry: Validates price action before execution

5. Direction-Specific Configuration

• LONG signals: Different quality thresholds than SHORT
• SHORT signals: Higher baseline difficulty, lower thresholds
• Momentum filters: Different for LONG (breakout) vs SHORT (reversal)
• Risk management: ADX-based runner SL positioning

---

📊 System Components

Core Services (Singletons)

• DriftService: Drift Protocol SDK wrapper, WebSocket subscriptions
• Position Manager: Software monitoring loop (2-second price checks)
• Pyth Price Monitor: Real-time oracle price feeds (WebSocket)
• Stop Hunt Tracker: 4-hour revenge window monitoring
• Blocked Signal Tracker: 30-minute price tracking for blocked signals
• Smart Validation Queue: Pullback confirmation system (30-second checks)

Key Workflows

1. Trade Execution: TradingView → n8n → check-risk → execute → database → Position Manager
2. Exit Management: Price check → TP/SL trigger → closePosition → database → Telegram notification
3. Startup Recovery: Database query → Drift validation → restore Position Manager → resume monitoring
4. Ghost Detection: Drift API check → database cleanup → Position Manager removal

Data Flow

TradingView Alert (5-min candle)
  ↓ [Webhook]
n8n Parse Signal Enhanced
  ↓ [HTTP POST]
/api/trading/check-risk
  ↓ [Quality score, cooldown, duplicates]
/api/trading/execute
  ↓ [Market order, TP/SL placement]
Database (Trade table)
  ↓ [State persistence]
Position Manager (monitoring)
  ↓ [2-second price checks]
Exit Detection (TP1/TP2/SL/Trailing)
  ↓ [Market close order]
Database Update (exit details)
  ↓ [P&L, exit reason, timestamps]
Telegram Notification

---

🔧 Configuration Architecture

Three-Layer Merge Priority

1. Per-symbol ENV vars (highest): SOLANA_*, ETHEREUM_*
2. Market config (code): SUPPORTED_MARKETS in config/trading.ts
3. Global ENV vars (fallback): MAX_POSITION_SIZE_USD, LEVERAGE
4. Default config (lowest): DEFAULT_TRADING_CONFIG

Key Configuration Files

• config/trading.ts - Central config with merge logic
• .env - Environment variables (482 lines)
• prisma/schema.prisma - Database schema
• .github/copilot-instructions.md - System documentation (6,400+ lines)

---

🚀 Adding New Architecture

When to Create Architecture Docs:

• Major system component (Position Manager, Drift client, etc.)
• Risk management system (leverage, stops, entry validation)
• Data flow pattern (TradingView → execution → monitoring)
• Critical decision (database-first vs in-memory, singleton vs multiple instances)

Template Structure:

# [Component Name]

**Purpose:** [One-line description]

## Architecture Decision
[Why this design was chosen, alternatives considered]

## Implementation
[Code structure, key classes, integration points]

## Data Flow
[How data moves through the component]

## Configuration
[ENV variables, defaults, merge priority]

## Error Handling
[Failure scenarios, recovery procedures]

## Verification
[How to test, expected behaviors, logs to watch]

## Deployment
[Restart requirements, migration steps]

## Lessons Learned
[What worked, what didn't, future improvements]

---

🔍 Finding Architecture Info

By Component:

• Leverage system → ADAPTIVE_LEVERAGE_SYSTEM.md
• Trailing stops → ATR_TRAILING_STOP_FIX.md
• Indicator versions → INDICATOR_VERSION_TRACKING.md
• Position sync → POSITION_SYNC_QUICK_REF.md

By Pattern:

• Singleton → All architecture docs mention singleton pattern
• Adaptive systems → ATR, Leverage, Trailing Stop docs
• Database-first → Position Sync, all architecture patterns
• Direction-specific → Leverage, Indicator docs

---

⚠️ Critical Architecture Constraints

Real Money System:

• Every architectural decision affects financial outcomes
• Database integrity is non-negotiable (write FIRST, read to restore)
• Position Manager MUST have TP/SL backup (on-chain orders can fail)
• Container restarts MUST restore full state (database = source of truth)

Performance Requirements:

• Position Manager: 2-second monitoring loop (not slower)
• Price feeds: WebSocket real-time (not HTTP polling)
• Order placement: <1 second execution (market orders)
• Database writes: Non-blocking (async, don't wait for confirmation)

Scalability Limits:

• Maximum 20 simultaneous positions tracked
• Maximum 10 trades per hour per symbol
• Drift SDK: 50 RPC calls/second burst, 10/second sustained
• PostgreSQL: 10 concurrent connections max

---

See ../README.md for overall documentation structure.