Comment Responder – Reviews

Route

• Path: /account/reviews
• Parent: README.md
• Nav group: Comment Responder in the authenticated account shell

This is the canonical shipped route location in the app. Do not introduce a separate /comment-responder/reviews route.

Purpose (business goal)

Provide an operator surface for triaging inbound customer reviews, inspecting full review context, generating compliant replies, and moving reviews through approval/send workflows without leaving the page.

The Reviews page is not a dashboard summary and not a plain table. It is a moderation and reply workflow surface.

User roles & permissions

• Manager
• Agent
• Workspace Admin
• Permissions (MVP/TBD):
  • comment_responder.view
  • comment_responder.reply
  • comment_responder.approve

Reference: Roles & Permissions Model

Architecture fit

This page fits the current platform architecture if implemented as an account-shell route with page-local filtering and selection behavior:

• route remains /account/reviews
• shell navigation remains unchanged
• review data is scoped to the current account surface
• workspace, platform, location, and rating filters are applied in-page

Reviews belong to the Comment Responder domain and are fed by connected review-platforms channels.

Layout structure

The page uses the standard account shell and a full-height operator layout.

1. Fixed top section

• page title: Reviews
• short supporting copy explaining the moderation/reply job of the page
• controls live in the same fixed top section:
  • search
  • workspace filter
  • platform filter
  • location filter
  • rating filter
  • sort control
  • expandable advanced filters panel

2. Compact metrics/status strip

Use an inline summary strip rather than large dashboard cards. Metrics derive from the currently filtered dataset.

Recommended metrics:

• Total reviews
• Attention
• Unreplied
• Pending approval
• Sent
• Average rating

3. Main content

Two-panel layout:

• Left: review queue
• Right: review detail + reply workflow

Recommended desktop split:

• queue column: fixed or semi-fixed width (360-420px)
• detail column: fills remaining width

Queue and detail must scroll independently. Avoid page-level scrolling once the page body is visible.

Review queue

Each row should include:

• reviewer identity (Unknown reviewer when missing)
• star rating
• platform
• location
• review excerpt
• relative timestamp
• status / attention treatment
• reply-state badge

Queue ordering

Default prioritization:

1. Attention-required reviews
2. Unreplied low-rating reviews
3. Pending approval reviews
4. Remaining reviews by newest

Filters

Supported in MVP:

• Workspace
• Platform
• Location
• Rating
• Reply state
• Attention only
• Date range
• Search by reviewer name, review body, location, and platform

Detail panel

Review header

• reviewer name
• platform
• rating
• location
• timestamp
• status and reply-state pills
• external review link when available

Review content

• full review body
• metadata row:
  • review id
  • workspace
  • updated timestamp
  • external review link when available

Suggested reply workspace

• editable draft reply area
• regenerate action
• approve action when permitted
• send action when permitted
• policy/compliance callouts
• provider-state callouts
• permission callouts when actions are disabled

Workflow / audit area

• reply state
• generated by / approved by / sent by when present in seeded data
• delivery failure or blocked state when applicable
• compact audit timeline

State model

Do not overload one status label. Reviews should use separate dimensions.

Review lifecycle

• new
• in_review
• approved
• sent
• closed

Attention flag

• requires_attention: boolean

Reply state

• none
• draft
• pending_approval
• sent
• failed

Policy signal

• safe
• needs_check
• blocked

Provider state

• live
• edited
• removed

Components used

• Comment Moderation View pattern: Component: Comment Moderation View

The Reviews page should follow the same moderation-first interaction model already documented for Comment Responder surfaces.

States

• Loading: queue/detail loading or provider sync lag
• Empty (no data at all): no reviews have synced yet
• Empty (filtered): no reviews match the current filters
• No selection: prompt user to select a review
• Error: provider outage / permission denied / reply validation failure
• Complete: queue + detail + reply workflow are visible
• Removed / edited upstream: persistent notice in detail when the source review changed or disappeared
• Permission-gated: disable actions clearly and explain why inline

Demo data model (minimum)

type DemoReview = {
  id: string;
  workspace_id: string;
  reviewer_name: string | null;
  reviewer_contact?: string | null;
  platform: "Trustpilot" | "Google Review" | "Yelp";
  location_name: string;
  rating: 1 | 2 | 3 | 4 | 5;
  body: string;
  created_at: string;
  updated_at: string;
  requires_attention: boolean;
  lifecycle: "new" | "in_review" | "approved" | "sent" | "closed";
  reply_state: "none" | "draft" | "pending_approval" | "sent" | "failed";
  policy_signal: "safe" | "needs_check" | "blocked";
  provider_state: "live" | "edited" | "removed";
  external_url?: string;
  draft_reply: string | null;
  suggested_reply: string | null;
  generated_by?: string | null;
  approved_by?: string | null;
  sent_by?: string | null;
  permissions: {
    canGenerate: boolean;
    canApprove: boolean;
    canSend: boolean;
    reason?: string | null;
  };
  timeline: DemoReviewTimelineEvent[];
};

Optional reply workflow / audit shape:

type DemoReviewTimelineEvent = {
  id: string;
  type:
    | "created"
    | "reply_generated"
    | "reply_edited"
    | "reply_approved"
    | "reply_sent"
    | "reply_failed"
    | "policy_flagged"
    | "provider_edited"
    | "provider_removed";
  label: string;
  actor?: string | null;
  timestamp: string;
};

Business logic (high-level)

• Replies must comply with policy constraints and may vary by platform rules.
• Metrics recalculate from the filtered dataset.
• Search and filters must not imply cross-workspace leakage when production wiring is added.
• Attention is a separate flag and may coexist with any lifecycle state.
• The UI must support approval-aware workflows even when send is not permitted.
• The shipped seeded implementation currently surfaces metadata and workflow callouts from:
  • policy_signal
  • provider_state
  • permissions
  • timeline

Domain refs:

• Domain: Comment Responder
• Domain: Channels
• Domain: Knowledge Bases

API dependencies (future)

• GET /comment-responder/reviews
• GET /comment-responder/reviews/{id}
• POST /comment-responder/reviews/{id}/generate-reply
• POST /comment-responder/reviews/{id}/approve-reply
• POST /comment-responder/reviews/{id}/send-reply

These are future targets and are not required for a seeded MVP implementation.

Enterprise constraints

• Location-based access controls (TBD)
• Workspace isolation must remain intact even when locations and platforms are filtered together

Edge cases

• Review edited upstream
• Review removed upstream
• Unknown reviewer identity
• Very long review body
• Blocked reply because of compliance policy
• Pending approval with no send permission

Security & compliance considerations

• Audit generate / approve / send actions
• Enforce permission gates on reply actions
• Avoid unnecessary exposure of reviewer PII in seeded data

Reference: Security & Compliance

Analytics events (if applicable)

• comment_responder.reply.generated
• comment_responder.reply.sent

Reference: Analytics Events (MVP)