Queue Dashboard - Quick Integration Guide 🚀

Time to integrate: 10 minutes

📋 Pre-requisites

✅ Backend running with queue endpoints
✅ Frontend-pwa running
✅ User authenticated
✅ Business context available

🔧 Integration Steps

Step 1: Add Route (2 minutes)

Find your router configuration file and add the queue monitoring route.

Option A: If using React Router

// apps/frontend-pwa/src/App.tsx or routes.tsx

import QueueMonitoringPage from "@/components/queue/QueueMonitoringPage";

// Add to your routes array:
{
  path: "/admin/queue",
  element: <QueueMonitoringPage />,
}

// Or with layout wrapper:
{
  path: "/admin",
  element: <AdminLayout />,
  children: [
    {
      path: "queue",
      element: <QueueMonitoringPage />,
    },
  ],
}

Option B: If using file-based routing

Create a new file at the appropriate location in your routing structure.

Add a link to your admin navigation menu.

Find your navigation component (sidebar, header, or admin menu):

// Example: apps/frontend-pwa/src/components/layout/Sidebar.tsx

import { Activity } from "lucide-react";
import { Link } from "react-router-dom";

// Add to your navigation items:
<Link 
  to="/admin/queue"
  className="flex items-center gap-3 px-4 py-2 hover:bg-muted rounded-lg"
>
  <Activity className="w-5 h-5" />
  <span>Queue Monitoring</span>
</Link>

// Or if using a navigation array:
const adminMenuItems = [
  // ... existing items
  {
    path: "/admin/queue",
    label: "Queue Monitoring",
    icon: Activity,
    permission: "queue:view",
  },
];

Step 3: Verify API Configuration (1 minute)

Ensure your API client is configured correctly:

// apps/frontend-pwa/src/lib/api.ts

// Should have the correct base URL
const API_BASE_URL = import.meta.env.VITE_API_URL || "http://localhost:3000/api";

Step 4: Test (4 minutes)

Navigate to the dashboard
```
http://localhost:5173/admin/queue
```
Verify stats load
- Should see 6 stat cards
- Numbers should populate
Test filters
- Click "Pending", "Failed", etc.
- Jobs list should update
Test actions
- Click "View" on a job → Modal opens
- Click "Retry" on failed job → Toast notification
- Click "Cancel" on pending → Confirmation dialog
Test refresh
- Click refresh button → Data reloads

🎨 Optional Customizations

Add Permissions (if using RBAC)

// Wrap the route with permission check
{
  path: "/admin/queue",
  element: (
    <RequirePermission permission="queue:view">
      <QueueMonitoringPage />
    </RequirePermission>
  ),
}

Add Page Title/Meta

// In QueueMonitoringPage.tsx
import { Helmet } from "react-helmet-async";

<Helmet>
  <title>Queue Monitoring | FlowPOS</title>
</Helmet>

Add to Admin Dashboard

// Show quick stats on main admin dashboard
import { useQueueStats } from "@/hooks/useQueueStats";

export function AdminDashboard() {
  const { stats } = useQueueStats();
  
  return (
    <div>
      {/* Other dashboard widgets */}
      
      <Card>
        <CardHeader>
          <CardTitle>Queue Status</CardTitle>
        </CardHeader>
        <CardContent>
          <div className="grid grid-cols-3 gap-4">
            <div>Pending: {stats?.pending ?? 0}</div>
            <div>Failed: {stats?.failed ?? 0}</div>
            <div>Processing: {stats?.processing ?? 0}</div>
          </div>
          <Link to="/admin/queue" className="text-primary text-sm mt-2 block">
            View Full Queue →
          </Link>
        </CardContent>
      </Card>
    </div>
  );
}

🔐 Security Considerations

Add Permission Checks

// In your permission system
export const QueuePermissions = {
  view: 'queue:view',
  retry: 'queue:retry',
  cancel: 'queue:cancel',
  delete: 'queue:delete',
  processManually: 'queue:process',
};

// Apply to buttons
{hasPermission('queue:retry') && (
  <Button onClick={handleRetry}>Retry</Button>
)}

Admin-Only Features

Hide sensitive actions for non-admin users:

// In QueueMonitoringPage.tsx
const { user } = useAuth();
const isAdmin = user?.role === 'admin';

{isAdmin && (
  <Button onClick={handleProcessNow}>
    Process Now (Admin)
  </Button>
)}

📊 Monitoring Setup

Add to Health Dashboard

// Create a health check component
import { useQueueStats } from "@/hooks/useQueueStats";

export function SystemHealthCheck() {
  const { stats } = useQueueStats();
  
  const isHealthy = 
    stats.pending < 100 &&
    stats.failed < 10 &&
    stats.processing < 20;
  
  return (
    <div className={isHealthy ? "text-green-600" : "text-red-600"}>
      Queue: {isHealthy ? "Healthy ✓" : "Unhealthy ✗"}
    </div>
  );
}

Set Up Alerts

// In useQueueStats.ts or separate monitoring hook
useEffect(() => {
  if (stats && stats.failed > 20) {
    // Send alert to Slack, email, etc.
    sendAlert('Critical: High failure rate in communication queue');
  }
}, [stats?.failed]);

🎯 Quick Start Checklist

Copy and check off:

🚨 Common Issues

"Cannot read property 'id' of null"

Cause: Business context not loaded
Fix: Add loading check in page component

"401 Unauthorized"

Cause: Token not being sent
Fix: Verify useAuth() hook is working

"Network Error"

Cause: Backend not running or wrong URL
Fix: Check backend is at http://localhost:3000

Stats showing zero for everything

Cause: No queue jobs exist yet
Fix: Trigger a communication to create queue jobs

🎉 You're Done!

After following these steps, you'll have:

✅ Fully functional queue monitoring dashboard
✅ Real-time stats with auto-refresh
✅ Job management capabilities
✅ Mobile-responsive UI
✅ Production-ready code

Navigate to /admin/queue and start monitoring! 🚀

📞 Need Help?

Documentation:

Full API: COMMUNICATION-QUEUE-API.md
Implementation: QUEUE-DASHBOARD-IMPLEMENTATION.md
cURL examples: COMMUNICATION-QUEUE-CURL-EXAMPLES.md

Next Steps:

Add permissions/RBAC
Set up alerting
Create scheduled reports
Build analytics dashboard

📋 Pre-requisites​

🔧 Integration Steps​

Step 1: Add Route (2 minutes)​

Step 2: Add Navigation Link (3 minutes)​

Step 3: Verify API Configuration (1 minute)​

Step 4: Test (4 minutes)​

🎨 Optional Customizations​

Add Permissions (if using RBAC)​

Add Page Title/Meta​

Add to Admin Dashboard​

🔐 Security Considerations​

Add Permission Checks​

Admin-Only Features​

📊 Monitoring Setup​

Add to Health Dashboard​

Set Up Alerts​

🎯 Quick Start Checklist​

🚨 Common Issues​

"Cannot read property 'id' of null"​

"401 Unauthorized"​

"Network Error"​

Stats showing zero for everything​

🎉 You're Done!​

📞 Need Help?​