Review Queue and Approval Channels

Post 5 in the HITL in Agentic Systems series. Post 4 covered the state machine and metadata. This post: what a review queue is, and which channels reviewers use to get notified and click approve/reject (Slack, email, dashboard).

Opening: "You have 3 items pending review"

When there is an approval gate, items in pending_review must reach the reviewer. A simple approach: a queue (list) that collects all waiting items; the user opens the dashboard and sees “You have 3 items pending review”, clicks each item, sees the content, and clicks Approve or Reject. Besides the dashboard, many teams use Slack (message with buttons) or email (link to the review page). This post clarifies what the queue is, how to prioritize, and how the channels compare.

1. Review queue — central list of items waiting

Value: Reviewers need one place to see all pending items — not open each workflow separately. The queue is a list that can be sorted (by time, priority), filtered (by type, team). After this you know how to design a minimal “pending review” screen.

Challenges: Many sources (many workflows, many item types) — one queue or separate queues per type? Different SLAs (deploy needs review in 15 minutes, content maybe 24h) → how to prioritize?

Design: Queue = collection of items with state = pending_review. Each item has: id, type (e.g. deploy, send_email), created_at, priority (optional), link to detail. List API: filter by type, sort by created_at or priority. Dashboard: table or card list, click to open detail and Approve/Reject/Modify buttons.

Solution: One global queue (all pending) or one queue per workflow — depends on scale. Prioritize by deadline/SLA: items close to timeout sort to the top. Implementation: “list pending” API + dashboard component; or integrate Slack/email to push a link to each item.

Implementation: Backend: query items with state=pending_review, join reviewed_by/reviewed_at if needed; return list. Frontend: show list, deep link to /approval/item/{id} to view and act. Post 6 covers identity (only show items the user is allowed to review).

2. Channels: Slack, email, dashboard

Value: Reviewers can get notified and act via Slack (fast, in the flow), email (review link), or dashboard (full context, clear audit). Each channel has trade-offs.

Challenges: Slack is fast but low context (may need to click through to dashboard or open link); email can be missed or go to spam; dashboard has full context but requires opening the app. Often combine: push notification via Slack/email, actual action in the dashboard (or Slack button if simple).

Design: Short comparison:

Solution: Notification: Slack message or email with short summary + link. Action: Dashboard (recommended) for full context and logging; or Slack button that sends an event to the backend (simple, less context). Email link: tokenized URL to the review page (one-time token, expire after X hours).

Implementation: Slack: webhook sends message, Block Kit button calls approve/reject API. Email: template with link https://app/approve?token=xxx. Dashboard: queue list + detail view + buttons. Post 6: identity and audit trail when the user acts from any channel.

3. Where the user clicks approve/reject

Value: Clear UX: notification “You have 3 items pending review” → click → see content (draft email, deploy plan, etc.) → click Approve / Reject / Modify. You need one “landing place” (dashboard or page from link) to perform the action and record audit.

Solution: Dashboard: list view (queue) + detail view (item content) + action buttons. Slack: message with buttons → click sends event → backend updates state and reviewed_by, reviewed_at. Email: link → web page with token → show content + buttons → backend handles. All channels call the same approve/reject API so state and audit stay consistent.

Implementation: Backend API: POST /approval/items/:id/approve, POST /approval/items/:id/reject (body may include reason). Middleware authenticates the user (session or token), checks permission (post 6), updates state and metadata, writes audit log. Post ends with a lead-in: post 6 covers who may review (identity, permissions) and the detailed audit trail.

Previous: States and State Machine (post 4). Next: Identity and Audit Trail (post 6).