Ponder

Fact Check Feature

Fact-check table, Appwrite function behavior, UI flow, caching, and history.

Purpose

The fact-check feature lets users verify a typed claim or an article-derived claim, reuses exact stored fact checks, calls Perplexity through an Appwrite Function when needed, and records signed-in history.

Tables

Primary table: fact_checks

Relevant columns:

• Legacy/current Flutter fields: claim, verdict, confidenceLevel, confidenceScore, source, sourceUrl, contextBlock, checkedAt, relatedContentId, language
• Newer function fields also present: confidence, explanation, citations, userId, createdAt

History table: user_fact_check_history

• userId
• factCheckId
• triggeredAt
• sourceContentId

Function

Function ID: fact_check

The function accepts:

{
  "claim": "Claim text",
  "userId": "optional user id"
}

It validates that the claim is present and no longer than 500 characters. It checks for a recent exact cache hit within seven days. If no cache hit exists, it calls Perplexity with model sonar, requesting JSON with verdict, confidence, explanation, and citations.

Successful responses include:

• claim
• verdict
• confidence
• explanation
• citations
• userId
• createdAt

The function stores rows in fact_checks when Appwrite endpoint, project ID, and API key are available.

Flutter Repository Flow

FactCheckRepository.checkClaim:

1. Trims the claim.
2. Calls findFactCheck for an exact normalized match in fact_checks.
3. Records signed-in history if a cache hit exists.
4. Executes fact_check when no exact cache row exists.
5. Parses the function payload into FactCheckResult.
6. Attempts related-content enrichment by exact sourceUrl or normalized title.
7. Persists relatedContentId back to the fact-check row when possible.
8. Records signed-in history in user_fact_check_history.

UI Flow

FactCheckScreen:

• Shows a claim composer.
• Seeds draft claims from article detail through factCheckDraftClaimProvider.
• Tracks article source context through factCheckDraftSourceContentIdProvider.
• Shows starter claims from recent fact-check rows, with fallback examples in the screen code.
• Enforces daily local limits before submission.
• Displays structured results with FactResultCard.
• Can open a related local article or external source URL.

Daily Limits

The screen uses shared_preferences keys:

• fc_date
• fc_count

Limits:

• Guest: 3 checks per day.
• Free: 5 checks per day.
• Premium: unlimited in the Flutter screen logic.

History

Signed-in users get private history rows in user_fact_check_history. ArchiveScreen shows a Fact Checks tab that pages through this history by triggeredAt and displays each result through FactResultCard.