Skip to content
SiteSwarm Platform Documentation

Critique Capability

Critique Platform Service & Capability Architecture (CRITIQUE_CAPABILITY.md)

1. Executive Summary & Platform-Hosted Topology

The Critique system enables business owners, operators, and review agents to pin visual, editorial, and functional feedback directly on live storefront interfaces during staging and preview evaluations.

Critique is implemented as a platform-hosted capability (CAPABILITY_MANAGEMENT.md, MULTI_WORKER_PLATFORM_SERVICES.md). Rather than embedding storage and critique management directly within each client application isolate, all feedback routes into a centralized platform Cloudflare Worker (services/critique) backed by dedicated Cloudflare D1 persistence:

flowchart LR
    subgraph ClientEnvironments["Client App Environments (apps/*)"]
        Local["Local Dev\n(localhost:<port>)"]
        Preview["PR Preview\n(preview-deploy)"]
        Staging["Internal Staging\n(staging-deploy)"]
    end


    subgraph PlatformService["Central Platform Service (services/critique)"]
        Entry["WorkerEntrypoint\n(RpcTarget + Fetch Router)"]
        Domain["CritiqueDomainService\n(Shared Validation & Dedup)"]
        DB[("Cloudflare D1\nsiteswarm-critique-db")]
        Entry --> Domain --> DB
    end


    Local & Preview & Staging -->|"Browser Dock: Authenticated HTTP\nWorker-to-Worker: Service Binding RPC"| Entry

2. Core Architectural Principles

  1. Environment Transcendence (Zero Siloed Feedback): Critiques are durable editorial records stored centrally and partitioned by tenantId. Feedback pinned on a mobile smartphone preview is immediately visible in local development and staging environments. Pinned critiques never disappear when an ephemeral preview worker is torn down.
  2. Dual-Access Interface Convention (RPC + HTTP):
    • Worker-to-Worker Service Binding RPC: Client workers bind CRITIQUE_SERVICE (services: [{ binding: "CRITIQUE_SERVICE", service: "siteswarm-critique" }]) and communicate via Cloudflare Worker RPC (WorkerEntrypoint). RPC methods provide direct, high-performance structured calls (list, create, updateStatus, getMetrics) without network overhead or manual JSON serialization.
    • Authenticated REST/HTTP Ingress: The client-side browser dock (<CritiqueOverlay /> in packages/capabilities/critique) communicates with services/critique via authenticated HTTP endpoints (/api/critiques, /api/critiques/:id, /api/critiques/:id/status) with tenant CORS validation.
  3. Cross-Version DOM Resilience: Each critique records the commit SHA and DOM selector where it was created. If CSS classes or markup change during refactoring, the overlay falls back to matching text content snippets and parent component boundaries.
  4. Zero Production Footprint: Review mode is strictly disabled in production client builds unless authenticated via Cloudflare Access staff credentials. When disabled, the overlay script is completely omitted from the HTML payload.

3. The 3-State Critique Lifecycle

Rather than a simple binary open/closed toggle, critiques move through a 3-state verification lifecycle:

stateDiagram-v2
    [*] --> open: Reviewer Pins Defect
    open --> addressed: Developer Commits Fix
    addressed --> open: Reopened (Fix Rejected)
    addressed --> resolved: Verified & Promoted
    resolved --> open: Reopened (Regression Detected)
    resolved --> [*]
State Lifecycle Stage In-Situ Overlay & System Behavior
open Action Required Defect is active and unresolved; pinned markers display prominently across all environments for that tenant.
addressed Ready for Visual Verification A fix has been committed and deployed; highlighted in the dock so reviewers can visually verify the resolution in-situ and either approve or reopen it.
resolved Verified & Closed Defect is verified and closed; hidden from active viewport overlays to maintain visual clarity.

4. Critique Rubric Mapping

Overlay critique tags align with SiteSwarm’s 4-Axis Red Pen Review Rubric (CLIENT_APP_REVIEW.md):

Overlay Tag Evaluation Axis Purpose
Too Buzzwordy Axis 1: Tone & Authenticity Flags corporate parody, sycophantic buzzwords, or marketing fluff.
Needs Restraint / Remove Badge Axis 2: Visual Restraint Flags badge clutter, neon borders, or typographic chaos.
Copy Edit Axis 3: Content Genuineness Corrects unverified claims, fabricated metrics, or typos.
Formatting Issue Axis 4: IA & Ergonomics Flags layout breakage, hidden content, or mobile touch issues.
Love This Positive Anchor Explicitly preserves a high-scoring section from unintended modification.

5. Persistence & Schema Architecture

Critique state is persisted in Cloudflare D1 SQLite (services/critique/migrations/0001_initial.sql). Key schema elements include:

  • id: Unique critique UUID.
  • tenant_id: Monorepo client identifier (e.g. bakery, auto-repair).
  • environment: Reporting environment (local, preview, staging).
  • selector: DOM path and XPath anchor.
  • target_text: Quoted text content for fuzzy matching resilience.
  • screenshot_url: Optional R2 presigned screenshot reference.
  • tag: Standardized rubric tag.
  • status: 'open' | 'addressed' | 'resolved' | 'dismissed'.
  • created_at, addressed_at, resolved_at: ISO 8601 audit timestamps.

Decisions Intentionally Deferred

  • Direct integration between @siteswarm/critique and external ticketing systems (GitHub Issues, Linear) is deferred; critiques remain lightweight in-situ review records.
  • Prospect-facing public feedback collection (unauthenticated end-user bug reporting) is deferred to preserve staff and client reviewer privacy.