Rhetoric Audit V3 — Use Case Documentation

Preconditions

• Public website is available.

Main Success Flow

1. 1Visitor lands on the homepage.
2. 2Visitor reviews core capabilities: bias spectrum, propaganda index, factual grounding, strategic silence, and 15 FME parameters.
3. 3Visitor views benchmark accuracy badge (100% band accuracy, FME V19.1).
4. 4Visitor reviews intended audiences: researchers, journalists, policy analysts, critical readers.
5. 5Visitor chooses to install the extension or create an account.

Alternate Flows

• Visitor leaves without creating an account.
• Visitor proceeds directly to Chrome extension installation.

Postconditions

• Visitor has enough product understanding to continue to onboarding or evaluation.

Preconditions

• User has internet access.
• Authentication service is available.

Main Success Flow

1. 1User opens sign-up or login form (web or extension popup auth shim).
2. 2User authenticates via email/password or Google OAuth.
3. 3If from extension: system detects ext=1 param, persists ext_id in sessionStorage.
4. 4System creates or validates the session and redirects to dashboard or /auth/ext-bridge.
5. 5If from extension: bridge page reads session and calls chrome.runtime.sendMessage with tokens.
6. 6Extension popup shows signed-in profile state. Bridge tab auto-closes after 2 seconds.

Alternate Flows

• Password mismatch prevents sign-up.
• Invalid credentials block login.
• OAuth callback fails and user is returned to error state.
• Extension ID mismatch causes bridge failure.

Postconditions

• User has authenticated session. Extension has stored tokens.

Preconditions

• User is using Chrome (Manifest V3 supported).

Main Success Flow

1. 1User opens Chrome Web Store listing.
2. 2User installs extension V3.
3. 3Extension background.js initializes and checks chrome.storage for existing session.
4. 4User browses to an article page.
5. 5Extension content.js runs layered gate: hard-skip → HARD_DENY hosts → SOFT_DENY → editorial path/slug/subdomain → DOM content score.
6. 6If gate passes: extension pill appears on page. If fails: pill suppressed.

Alternate Flows

• Page fails editorial gate (e.g. app, listing, PDF) → pill suppressed.
• User is on a HARD_DENY host → pill suppressed.
• Extension is disabled or removed.

Postconditions

• Extension is active. Pill appears on editorial article pages automatically.

Preconditions

• Extension V3 is installed.
• Page passes editorial gate (≥250 words, ≥3 paragraphs, not a HARD_DENY host).

Main Success Flow

1. 1content.js passes gate and emits ra-loading message.
2. 2Inline panel opens (panel.html / 820×640 iframe overlay).
3. 3Panel sends article text to POST /api/analyze.
4. 4System checks dedup cache (URL hash + content hash).
5. 5Cache hit: panel renders cached result. 0 credits consumed.
6. 6Cache miss: LLM pipeline runs (GPT-4o-mini primary).
7. 7Result stored. Anonymous: no history. Registered: added to scan_events.
8. 8Panel renders: bias spectrum, manipulation risk, heatmap, span highlights.
9. 9If authenticated: scan added to history.

Primary Outputs

Alternate Flows

• Cache miss + LLM timeout → panel shows error state with retry.
• Anonymous quota exhausted → panel shows Sign In CTA.
• SPA navigation: MutationObserver re-injects pill after DOM swap.

Postconditions

• Analysis visible in extension panel. Credit consumed only on cache miss for registered users.

Preconditions

• User is authenticated.
• Cache miss (if cache hit: 0 credits consumed).
• LLM service is available.

Main Success Flow

1. 1User provides article URL or raw text.
2. 2System normalizes URL (strips utm_*, fbclid, ref, etc.) and hashes.
3. 3System checks dedup cache.
4. 4Cache hit: renders cached result, no credit deducted.
5. 5Cache miss: validates request, checks credit balance, runs FME V19.1 pipeline.
6. 6Pipeline: preprocess → chunked span annotator → grounding orchestrator → deterministic aggregator → validator.
7. 7Result stored in scans table. scan_event logged. 1 credit deducted.
8. 8System displays full 15-parameter result set.
9. 9System emails scan-complete summary if preference is enabled.

Primary Outputs

Alternate Flows

• Insufficient credits → user prompted to upgrade.
• LLM error → user shown error, credit not deducted.
• Malformed request → validation fails, 422 returned.

Postconditions

• Scan result in user history. Credit deducted on cache miss only.

Preconditions

• Scan result exists.

Main Success Flow

1. 1User opens scan result.
2. 2System renders bias spectrum with 5-band label.
3. 3System renders manipulation risk gauge with calibrated V19.1 score.
4. 4System renders heatmap strip showing paragraph-level manipulation heat.
5. 5User clicks a highlighted span → tooltip shows technique label + quoted text.
6. 6System renders 15 FME parameter cards.
7. 7System renders factual grounding section with verified/unverified claims.
8. 8System renders EIS composite score.
9. 9User may initiate PDF export or share flow from this view.

Primary Outputs

Alternate Flows

• Span offsets fail to re-anchor → highlights silently suppressed.
• Grounding data unavailable → section shows partial results with disclaimer.

Postconditions

• User has full forensic understanding of article's rhetorical structure.

Preconditions

• Scan result exists.
• Article contained ≥1 factual_claim span.

Main Success Flow

1. 1User opens the Claim Verification card in scan results.
2. 2System displays per-claim rows: claim text, verification status (Verified/Unverified/Disputed), source provenance.
3. 3Provenance shows: Google FCT label, Wikidata entity match, Wikipedia summary, or Tavily corroboration.
4. 4User may click source link to open external reference.
5. 5System shows grounding coverage rate for the article.

Alternate Flows

• All external grounding APIs unavailable → section shows 'Grounding temporarily unavailable'.
• Article has no factual_claim spans → section shows 'No verifiable claims detected'.

Postconditions

• User understands factual accuracy signals in the article.

Preconditions

• Scan result is open in extension panel or web dashboard.

Main Success Flow

1. 1User clicks Export PDF.
2. 2Client-side pdf-builder.js constructs 14-page report: cover, exec summary, bias chart, manipulation gauge, heatmap, FME parameter pages, factual claims ledger, methodology reference.
3. 3window.print() launches browser print dialog.
4. 4User saves as PDF.

Alternate Flows

• Browser print dialog cancelled → no PDF generated.
• Complex article layout causes chart rendering issues → user retries or uses alternative export.

Postconditions

• 14-page annotated PDF saved to user's device.

Preconditions

• An analysis result exists.
• User has set scan to public (or uses native share which defaults to public URL).

Main Success Flow

1. 1User clicks Share.
2. 2System generates /s/{shortcode} URL.
3. 3User copies link or uses native share API.
4. 4Recipient opens /s/{shortcode}.
5. 5System checks scan privacy setting.
6. 6If public: renders summary view with selected FME fields.
7. 7If private: returns 404 or access-denied.

Alternate Flows

• Scan is private → shareable link not generated until user toggles to public.
• Shortcode not found → 404 page.

Postconditions

• Public scan summary viewable by recipient without dashboard login.

Preconditions

• User is authenticated as scan owner.
• Scan result exists.

Main Success Flow

1. 1User clicks privacy toggle on scan.
2. 2System calls toggle_scan_privacy RPC (Supabase) to flip is_public flag.
3. 3If toggled to public: /s/{shortcode} becomes accessible.
4. 4If toggled to private: /s/{shortcode} returns 404.
5. 5Toggle state reflected in UI immediately.

Alternate Flows

• User is not scan owner → toggle not shown.
• RPC fails → UI shows error, state reverted.

Postconditions

• Scan privacy state updated. Shortcode visibility reflects new setting.

Preconditions

• User is authenticated.

Main Success Flow

1. 1User opens dashboard.
2. 2System displays KPIs: total scans, average EIS, manipulation risk distribution, fallacy rate, credits remaining.
3. 3System shows corpus-level analytics: Manufactured Crisis Index, ideology cartography, Emotional Resonance Fever Chart.
4. 4User views publisher leaderboards (top-5 / bottom-5 by EIS).
5. 5User navigates to scan history or analytics sub-sections.

Alternate Flows

• User has no scans → empty state with onboarding CTA.

Postconditions

• User understands personal analysis patterns, corpus signals, and account status.

Preconditions

• User is authenticated.

Main Success Flow

1. 1User opens Scan History view.
2. 2System lists scans: title, bias, manipulation risk, fallacy, evidence, DOK, date, cache hit indicator.
3. 3User searches by text or filters by ideology, date range.
4. 4User opens a previous scan to view full result.

Alternate Flows

• No scans match filters.
• Pagination for large result sets.

Postconditions

• User can locate and review historic analyses.

Preconditions

• User is authenticated as Pro tier.
• User has at least 2 credits.
• Edge function and LLM services available.

Main Success Flow

1. 1User opens Intelligence Brief module.
2. 2User enters search terms and selects sources (X, Reddit, News, YouTube, Web, Financial).
3. 3System validates payload and checks rate limits.
4. 4System calls fetch-intelligence edge function to gather normalized signals.
5. 5System sends signal set to FME pipeline.
6. 6System validates and stores resulting brief.
7. 7System deducts 2 credits.
8. 8System presents results: executive summary, authenticity signals, emotion profile, narrative clusters, risk assessment, platform breakdown.

Primary Outputs

Alternate Flows

• Insufficient credits → insufficient-credit response.
• Rate limit exceeded.
• Partial source failure → partial results accepted.
• No usable signal → brief cannot be generated.

Postconditions

• Intelligence Brief stored and retrievable from history.

Preconditions

• User is authenticated as Pro tier.

Main Success Flow

1. 1User opens Intelligence Brief history tab.
2. 2System lists previous brief records.
3. 3User selects a brief.
4. 4System loads saved brief results.

Alternate Flows

• No previous briefs exist.

Postconditions

• User can continue analysis using saved brief outputs.

Preconditions

• User is authenticated.
• Stripe service available.

Main Success Flow

1. 1User opens Billing page.
2. 2System displays plan tiers (Free / Plus $5/mo / Pro $29/mo) and credit packs.
3. 3User selects plan or credit pack.
4. 4System creates Stripe Checkout session.
5. 5User completes payment.
6. 6System records billing event and applies plan/credits.
7. 7User returns with updated quota.

Alternate Flows

• User cancels checkout.
• Stripe session creation fails.
• Payment succeeds but application is delayed → requires reconciliation.

Postconditions

• User has upgraded tier or additional credits.

Preconditions

• User is authenticated.

Main Success Flow

1. 1User opens Settings.
2. 2User updates display name.
3. 3User toggles low-credit and scan-complete notifications.
4. 4User saves changes.
5. 5System updates profile record.

Alternate Flows

• Save fails → error shown.

Postconditions

• Profile and notification preferences updated.

Preconditions

• User is authenticated.
• User types DELETE to confirm.

Main Success Flow

1. 1User opens delete account modal.
2. 2System explains consequences.
3. 3User confirms with DELETE.
4. 4System calls delete-account endpoint.
5. 5Backend reassigns retained analysis records per operational policy.
6. 6Backend removes user profile and auth record.
7. 7User signed out and redirected.

Alternate Flows

• User closes modal without confirming.
• Confirmation text incorrect.
• Partial deletion → support follow-up required.

Postconditions

• User account no longer exists for login. Scan data retained per policy.

Preconditions

• User opted in.
• Resend email service available.

Main Success Flow

1. 1User activity changes account or scan status.
2. 2System evaluates notification rules.
3. 3Low-credit (<3) or scan-complete condition met → email generated.
4. 4Email sent to registered address via Resend.

Alternate Flows

• Email provider unavailable.
• Notification preference disabled.

Postconditions

• User receives informational email when conditions met.