agmission/Development/server/docs/DLQ_INDEX.md

DLQ Documentation Index

Navigation: 📖 Index | 🚀 Quick Start | 📚 API Reference | 🔧 Operations | 🏗️ System Guide

---

Complete documentation for the Dead Letter Queue (DLQ) system.

Quick Links

• 🚀 Quick Start Guide - Get started in 5 minutes
• 📖 API Reference - Complete API documentation
• 🔧 Operations Guide - Advanced operations and troubleshooting
• 🏗️ System Guide - Architecture and internals

Architecture Overview

The DLQ system provides global, queue-native operations for managing failed tasks across all queue types:

flowchart TB
    subgraph API["Global DLQ API"]
        endpoint["/api/dlq/:queueName/*"]
    end
    
    subgraph Queues["Supported Queues"]
        pt[partner_tasks]
        jobs[dev_jobs]
        future[Future queues...]
    end
    
    endpoint --> pt
    endpoint --> jobs
    endpoint --> future
    
    style API fill:#e1f5ff
    style Queues fill:#f0f0f0

Supported Queues:

• partner_tasks (partner log processing)
• dev_jobs (job processing)
• Any future queue types (notifications, analytics, etc.)

Key Features:

• ✅ Direct RabbitMQ operations (no MongoDB coupling)
• ✅ Supports multiple queue types
• ✅ Preserves original message content
• ✅ Works with any task type

---

Documentation Structure

Getting Started

1. DLQ Quick Start
   • Web dashboard access
   • Common operations
   • API examples
   • Troubleshooting basics

API Documentation

2. DLQ API Reference
   • All endpoints with examples
   • Request/response formats
   • Authentication
   • Error handling

Operations & Maintenance

3. DLQ Operations Guide
   • Monitoring strategies
   • Manual recovery procedures
   • Multi-queue operations
   • Best practices
   • Alert thresholds

System Architecture

4. DLQ System Guide
   • Architecture overview
   • Component details
   • Message flow
   • Integration patterns

---

Quick Examples

View DLQ Messages

curl http://localhost:4100/api/dlq/partner_tasks/messages?limit=20 \
  -H "Authorization: Bearer $TOKEN"

Retry All Messages

curl -X POST http://localhost:4100/api/dlq/partner_tasks/retryAll \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"maxMessages": 50}'

Multiple Queues

# Partner queue
curl -X POST http://localhost:4100/api/dlq/partner_tasks/retryAll ...

# Job queue
curl -X POST http://localhost:4100/api/dlq/dev_jobs/retryAll ...

# Future queue (no code changes needed!)
curl -X POST http://localhost:4100/api/dlq/notifications/retryAll ...

---

Tools & Interfaces

Web Dashboard

https://localhost:4100/dlq-monitor.html

• Real-time statistics
• View messages
• One-click retry
• Queue selection

API Integration

curl http://localhost:4100/api/dlq/:queueName/stats \
  -H "Authorization: Bearer $TOKEN"

---

Related Documentation

• Worker Documentation
• API Documentation
• Postman Collection

---

Archived Documentation

Old partner-specific documentation has been moved to archived/:

• These files document the pre-refactoring implementation
• Kept for historical reference only
• See archived/README.md for migration guide

---

Change Log

December 19, 2025 - Global DLQ Architecture Refactoring

• Moved from /api/partners/dlq/* to /api/dlq/:queueName/*
• Created new global documentation set
• Archived old PARTNER_DLQ_*.md files
• Support for multiple queue types

Previous - Partner-specific implementation

• See archived documentation for history

---

Contributing

When updating DLQ documentation:

1. Update the appropriate guide based on change type:

   • API changes → Update API Reference
   • Operations → Update Operations Guide
   • Architecture → Update System Guide

2. Keep examples consistent across all docs

3. Update this index if adding new documentation files

4. Test all curl examples before committing

---

Support

For questions or issues:

• Check Troubleshooting section
• Review System Guide for architecture details
• Contact: trungh@agnav.com