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