System Architecture

FactHarbor system architecture including POC simplifications and full system design

1. Architecture Evolution

FactHarbor will be built in phases, with architecture complexity increasing as we validate core capabilities.

1.1 POC1 Architecture (Simplified)

Goal: Validate core AI capability with minimal complexity

Components:

• Single AKEL API call (Claude Sonnet 4.5)
• Gates 1 & 4 (claim validation, verdict confidence)
• Basic UI display
• Manual quality tracking

Data Storage: Minimal (stateless or simple SQLite)

1.2 POC2 Architecture (Enhanced)

Goal: Add complete quality framework and evidence deduplication

New Components:

• Scenario generation
• Evidence deduplication system
• Gates 2 & 3 (evidence relevance, scenario coherence)
• Quality metrics dashboard

Data Storage: Enhanced (claims, scenarios, evidence, metrics)

1.3 Full System Architecture (V1.0+)

Goal: Production-ready multi-component system

Production Components:

• Multi-component AKEL pipeline
• Review workflow system
• Audit sampling framework
• Federation architecture
• Full data model (PostgreSQL + Redis + S3)

2. Quality Gate Architecture

2.1 Quality Gate System

Purpose: Prevent low-quality/hallucinated content from publication

2.2 Gate Implementation by Phase

Hardening means: Thresholds validated, edge cases handled, <5% failure rate

3. Data Architecture

3.1 POC Data Model (Simplified)

Storage: SQLite or minimal database

Entities:

• Articles (input text/URL)
• Claims (extracted from articles)
• Verdicts (per claim)
• Quality metrics (aggregated)

No complex relationships, versioning, or scenarios

3.2 Full System Data Model (V1.0+)

Storage: PostgreSQL (primary), Redis (cache), S3 (documents)

Core Entities:

• Claims (with versions, clustering)
• Scenarios (interpretations of claims)
• Evidence (deduplicated, provenance tracked)
• Verdicts (per scenario, versioned)
• Reviews (human oversight)
• Quality metrics (per component, aggregated)

Complex relationships, full audit trail, federation support

4. Component Architecture

4.1 AKEL Orchestrator

POC: Single API call  
Full System: Multi-component orchestration

Responsibilities:

• Route input through component pipeline
• Manage component state
• Handle errors and retries
• Coordinate quality gates
• Trigger review workflows

4.2 Quality Gate Validator

All Phases: Present but evolving complexity

Responsibilities:

• Execute all configured gates
• Aggregate gate results
• Make publication decisions
• Generate explanatory messages
• Log quality metrics

4.3 Review Queue Manager

POC: Not present  
Beta 0+: Optional  
V1.0: Full implementation

Responsibilities:

• Route low-confidence verdicts to review
• Manage reviewer assignments
• Track review status
• Implement audit sampling
• Generate review metrics

5. Architecture Decisions

5.1 Why Single AKEL Call for POC?

Rationale:

• Validates core capability fastest
• Simplest to implement and test
• Fail-fast if AI fundamentally can't do task
• Learn prompt engineering before architecting components
• Reduce moving parts during initial testing

Trade-off: Less granular control, harder to optimize individual steps

5.2 Why Add Components in V1.0?

Rationale:

• Better error handling per step
• Independent optimization of each component
• Easier to add new capabilities
• Better observability and debugging
• Supports federation (multiple FactHarbor instances)

Trade-off: More complexity, more to maintain

6. Related Pages

• Requirements - System requirements
• Design - UI/UX design
• Roadmap - Implementation phases
• POC1 - POC1 details
• POC2 - POC2 details

Document Status: ✅ Architecture Specified (POC1, POC2, Full System)  
Version: V0.9.70