# DLQ Documentation Index

**Navigation:** [📖 Index](DLQ_INDEX.md) | [🚀 Quick Start](DLQ_QUICKSTART.md) | [📚 API Reference](DLQ_API_REFERENCE.md) | [🔧 Operations](DLQ_OPERATIONS.md) | [🏗️ System Guide](DLQ_SYSTEM_GUIDE.md)

---

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

## Quick Links

- 🚀 [Quick Start Guide](DLQ_QUICKSTART.md) - Get started in 5 minutes
- 📖 [API Reference](DLQ_API_REFERENCE.md) - Complete API documentation
- 🔧 [Operations Guide](DLQ_OPERATIONS.md) - Advanced operations and troubleshooting
- 🏗️ [System Guide](DLQ_SYSTEM_GUIDE.md) - Architecture and internals

## Architecture Overview

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

```mermaid
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](DLQ_QUICKSTART.md)**
   - Web dashboard access
   - Common operations
   - API examples
   - Troubleshooting basics

### API Documentation

2. **[DLQ API Reference](DLQ_API_REFERENCE.md)**
   - All endpoints with examples
   - Request/response formats
   - Authentication
   - Error handling

### Operations & Maintenance

3. **[DLQ Operations Guide](DLQ_OPERATIONS.md)**
   - Monitoring strategies
   - Manual recovery procedures
   - Multi-queue operations
   - Best practices
   - Alert thresholds

### System Architecture

4. **[DLQ System Guide](DLQ_SYSTEM_GUIDE.md)**
   - Architecture overview
   - Component details
   - Message flow
   - Integration patterns

---

## Quick Examples

### View DLQ Messages
```bash
curl http://localhost:4100/api/dlq/partner_tasks/messages?limit=20 \
  -H "Authorization: Bearer $TOKEN"
```

### Retry All Messages
```bash
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
```bash
# 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
```
http://localhost:4100/dlq-monitor.html
```
- Real-time statistics
- View messages
- One-click retry
- Queue selection

### API Integration
```bash
curl http://localhost:4100/api/dlq/:queueName/stats \
  -H "Authorization: Bearer $TOKEN"
```

---

## Related Documentation

- [Worker Documentation](../README.md#workers)
- [API Documentation](../README.md#api)
- [Postman Collection](Partner_DLQ_API.postman_collection.json)

---

## Archived Documentation

Old partner-specific documentation has been moved to [`archived/`](archived/):
- These files document the pre-refactoring implementation
- Kept for historical reference only
- See [`archived/README.md`](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](DLQ_API_REFERENCE.md)
   - Operations → Update [Operations Guide](DLQ_OPERATIONS.md)
   - Architecture → Update [System Guide](DLQ_SYSTEM_GUIDE.md)

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](DLQ_OPERATIONS.md#troubleshooting) section
- Review [System Guide](DLQ_SYSTEM_GUIDE.md) for architecture details
- Contact: trungh@agnav.com