learning_ai_invt_trdg/backend/ADMIN_TRADE_CONTROL_QUICK_REF.md

Admin Trade Control - Quick Reference

🎯 What It Does

Allows admin users to pause and resume auto-trading from the dashboard.

• When PAUSED: No new trade entries are placed
• When RUNNING: Normal auto-trading resumes
• Always: Existing positions continue to be managed (exits, SL, TP)

---

🔐 Security

Check	Implementation
Authentication	All endpoints require valid JWT token
Authorization	Pause/Resume require role = 'admin'
UI Guards	Controls hidden for non-admin users
Audit Logs	All actions logged with user and reason

---

📡 API Endpoints

Get Status

GET /internal/trading/status
Authorization: Bearer <token>

Response:
{
  "mode": "RUNNING",
  "lastChangedBy": "admin@example.com",
  "lastChangedAt": 1708200000000,
  "reason": "Manual resume"
}

Pause Trading

POST /internal/trading/pause
Authorization: Bearer <admin-token>
Content-Type: application/json

{
  "reason": "Market volatility"
}

Response:
{
  "success": true,
  "status": { "mode": "PAUSED", ... }
}

Resume Trading

POST /internal/trading/resume
Authorization: Bearer <admin-token>
Content-Type: application/json

{
  "reason": "Conditions normalized"
}

Response:
{
  "success": true,
  "status": { "mode": "RUNNING", ... }
}

---

🖥️ UI Components

Header Badge (All Pages)

┌─────────────────────────┐
│ ⏸️ Trading Paused       │  ← Orange when paused
│ No new entries          │
└─────────────────────────┘

┌─────────────────────────┐
│ ▶️ Trading Active       │  ← Green when running
│ Entries allowed         │
└─────────────────────────┘

Admin Tab Controls

Trading Control
┌───────────────────────────────────────────┐
│ AUTO-TRADING: PAUSED                      │
│ No new positions will be opened.          │
│ Existing positions are still managed.     │
│                                           │
│ Last Changed: 2026-02-17 5:30 PM          │
│ by admin@example.com                      │
└───────────────────────────────────────────┘

┌──────────────────┐  ┌──────────────────────┐
│ ⏸️ Pause Auto    │  │ ▶️ Resume Auto       │
│    Trading       │  │    Trading           │
│ (disabled)       │  │ (enabled)            │
└──────────────────┘  └──────────────────────┘

⚠️ Safety Note: Pausing blocks new entries only.
   Existing positions continue to be managed.

---

🔧 Code Integration

Check if Paused

import { healthTracker } from './services/healthTracker';

if (healthTracker.isPaused()) {
    logger.info('Entry blocked: Trading is paused');
    return;
}

Programmatic Control

// Pause
healthTracker.recordTradingControl({
    mode: 'PAUSED',
    lastChangedBy: 'system',
    lastChangedAt: Date.now(),
    reason: 'Automated safety pause'
});

// Resume
healthTracker.recordTradingControl({
    mode: 'RUNNING',
    lastChangedBy: 'system',
    lastChangedAt: Date.now(),
    reason: 'Conditions normalized'
});

---

🛡️ Enforcement Points

File	Line	What It Does
AutoTrader.ts	106-109	Blocks new entries when paused
TradeExecutor.ts	531-534	Blocks openPosition when paused

What Continues:

• ✅ Exit orders
• ✅ Stop-loss monitoring
• ✅ Take-profit monitoring
• ✅ Position reconciliation
• ✅ Order status sync

---

💾 State Persistence

In-Memory (HealthTracker)
    ↓
Disk (bot_state.json)
    ↓
Database (Supabase)

On Restart:

1. Load from Supabase (preferred)
2. Fallback to bot_state.json
3. Default to RUNNING if not found

---

🧪 Testing Checklist

Backend

• Pause blocks new entries
• Resume allows new entries
• Existing positions continue when paused
• State persists across restart
• Non-admin gets 403

Frontend

• Pause button disabled when paused
• Resume button disabled when running
• Header badge shows correct status
• Error displayed on API failure
• Loading state shown during API call

---

📊 Monitoring

Metrics to Track

• Pause/resume event count
• Blocked entry attempts while paused
• Pause duration (time between pause/resume)
• Who paused (user tracking)

Alerts

• Trading paused > 1 hour
• Multiple pause/resume cycles in short time
• Pause during high volatility

---

🚨 Troubleshooting

Issue: Pause button not working

Check:

1. User has role = 'admin' in profile
2. Valid JWT token in request
3. Backend logs for errors
4. Network tab for API response

Issue: Status not updating in UI

Check:

1. WebSocket connection active
2. health_update events received
3. Browser console for errors
4. Refresh page to force sync

Issue: Entries still being placed when paused

Check:

1. Backend logs show pause enforcement
2. healthTracker.isPaused() returns true
3. AutoTrader/TradeExecutor checking pause state
4. No cached state in trading loop

Issue: State lost after restart

Check:

1. bot_state.json exists and readable
2. Supabase connection working
3. loadState() called on startup
4. Logs show state restoration

---

📚 Documentation Files

File	Purpose
ADMIN_TRADE_CONTROL_SUMMARY.md	Executive summary
ADMIN_TRADE_CONTROL_IMPLEMENTATION.md	Full implementation guide
ADMIN_TRADE_CONTROL_TEST_PLAN.md	Testing requirements
ADMIN_TRADE_CONTROL_ARCHITECTURE.md	Visual diagrams
ADMIN_TRADE_CONTROL_QUICK_REF.md	This quick reference

---

✅ Pre-Production Checklist

• All backend unit tests pass
• All frontend component tests pass
• Integration tests pass
• Manual testing completed
• Security review completed
• Documentation reviewed
• Audit logging verified
• State persistence verified
• Error handling verified
• UI/UX reviewed

---

🎉 Quick Start

For Admins

1. Login as admin user
2. Go to Admin tab (🛡️)
3. Find "Trading Control" section
4. Click "Pause" or "Resume"
5. Check header badge for status

For Developers

1. Read ADMIN_TRADE_CONTROL_IMPLEMENTATION.md
2. Review enforcement points in code
3. Run test suite
4. Deploy to staging
5. Verify functionality
6. Deploy to production

---

🔗 Related Systems

• Health Tracker: Stores trading control state
• API Server: Exposes control endpoints
• AutoTrader: Enforces pause on entries
• TradeExecutor: Enforces pause on openPosition
• WebSocket: Broadcasts state updates
• Dashboard: Displays status and controls

---

📞 Support

Issues? Check:

1. Backend logs: bytelyst-trading-bot-service/logs/
2. Frontend console: Browser DevTools
3. API responses: Network tab
4. State file: bot_state.json

Questions? See:

• Implementation guide
• Test plan
• Architecture diagram