System Design

Last modified by Robert Schaub on 2025/12/22 13:50

System Design

UI/UX design for FactHarbor including POC and production interfaces

1. Design Philosophy

Core Principles:

Transparency First: Show how verdicts were reached
2. Clarity Over Completeness: Don't overwhelm users
3. Progressive Disclosure: Details available on demand
4. Quality Indicators Visible: Users should see confidence levels immediately
5. Mobile-First: Majority of users on mobile devices

2. POC1 Interface Design

2.1 Input Screen

┌──────────────────────────────────────┐
│ FactHarbor - Fact Analysis POC      │
├──────────────────────────────────────┤
│                                       │
│ Paste article text or URL:          │
│ ┌─────────────────────────────────┐ │
│ │                                 │ │
│ │ (text input area)              │ │
│ │                                 │ │
│ └─────────────────────────────────┘ │
│                                       │
│         [ Analyze ]                   │
│                                       │
│ Note: This is a POC. Results are    │
│ AI-generated and may contain errors.│
└──────────────────────────────────────┘

Design Notes:

Simple, single-purpose interface
Clear POC disclaimer
No authentication/accounts needed

2.2 Results Display

┌──────────────────────────────────────┐
│ FactHarbor Analysis Results         │
├──────────────────────────────────────┤
│                                       │
│ Quality Score: 8.5/10 ✅           │
│ Quality Gates: 2/2 Passed           │
│                                       │
│ ═══════════════════════════════════ │
│                                       │
│ 📋 Claims Found: 3 verifiable       │
│      (2 non-verifiable filtered)     │
│                                       │
│ ─────────────────────────────────── │
│                                       │
│ CLAIM 1: [claim text]               │
│ Verdict: ✅ WELL-SUPPORTED (85%)    │
│ Sources: 4                           │
│ [Show Details ▼]                    │
│                                       │
│ ─────────────────────────────────── │
│                                       │
│ CLAIM 2: [claim text]               │
│ Verdict: ⚠️ PARTIALLY SUPPORTED (65%)│
│ Sources: 2                           │
│ [Show Details ▼]                    │
│                                       │
│ ─────────────────────────────────── │
│                                       │
│ BLOCKED CLAIM: [opinion text]       │
│ ❌ Non-factual (Opinion detected)   │
│ Explanation: Contains subjective     │
│ language ("best", "should")          │
│                                       │
└──────────────────────────────────────┘

Design Features:

Quality score prominently displayed
Color coding for verdict confidence
Expandable details (progressive disclosure)
Clear blocked claims with explanations

2.3 Claim Detail View

┌──────────────────────────────────────┐
│ CLAIM: [full claim text]            │
├──────────────────────────────────────┤
│                                       │
│ Verdict: ✅ WELL-SUPPORTED          │
│ Confidence: 85% (HIGH)               │
│                                       │
│ Evidence Sources: 4                  │
│ ┌──────────────────────────────────┐│
│ │ 📄 Source 1: Reuters              ││
│ │    Quality: 0.9 (High)            ││
│ │    [Supports claim]               ││
│ │    [View source →]                ││
│ ├──────────────────────────────────┤│
│ │ 📄 Source 2: BBC                  ││
│ │    Quality: 0.8 (High)            ││
│ │    [Supports claim]               ││
│ │    [View source →]                ││
│ └──────────────────────────────────┘│
│                                       │
│ Reasoning:                           │
│ [AI-generated explanation of verdict]│
│                                       │
│ Quality Checks:                      │
│ ✅ Gate 1: Factual claim            │
│ ✅ Gate 4: Sufficient evidence       │
│                                       │
└──────────────────────────────────────┘

3. POC2 Interface Enhancements

3.1 Added Features

Scenario Display:
┌──────────────────────────────────────┐
│ CLAIM: [text]                       │
├──────────────────────────────────────┤
│                                       │
│ Scenarios Evaluated: 2               │
│                                       │
│ 📍 Scenario A: [interpretation]     │
│     Verdict: WELL-SUPPORTED (80%)    │
│     [Show details ▼]                 │
│                                       │
│ 📍 Scenario B: [interpretation]     │
│     Verdict: UNCERTAIN (45%)         │
│     [Show details ▼]                 │
│                                       │
└──────────────────────────────────────┘

Evidence Provenance:

Show if multiple sources cite same underlying evidence
Display deduplication results
Provenance chain visualization

Quality Metrics Dashboard:

Internal view showing all 4 gates
Historical performance trends
Hallucination rate tracking

4. Full System Design (V1.0+)

4.1 Additional Features

User Accounts:

Save analyses
Track corrections
Contribute feedback

Advanced Search:

Find previous analyses
Filter by topic, verdict type
Sort by date, relevance

Corrections Banner:
┌──────────────────────────────────────┐
│ ⚠️ This analysis was corrected │
│ [View correction log →] │
└──────────────────────────────────────┘

Public Quality Dashboard:

Real-time metrics
Transparency reports
Historical trends

5. Responsive Design

Mobile-First Approach:

Single column layout
Touch-friendly targets
Collapsible sections by default
Fast load times

Desktop Enhancements:

Multi-column layout where appropriate
Side-by-side evidence comparison
Advanced filters always visible

6. Accessibility

WCAG 2.1 AA Compliance:

Keyboard navigation
Screen reader support
Color contrast ratios
Alternative text for icons
Focus indicators

7. Related Pages

Architecture - System architecture
Requirements - UI requirements
Roadmap - Implementation phases

Document Status: ✅ Design Specified (POC1, POC2, V1.0)
Version: V0.9.70