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 The [diagram] macro is a standalone macro and it cannot be used inline. Click on this message for details.
This macro generates standalone content. As a consequence you need to make sure to use a syntax that separates your macro from the content before and after it so that it's on a line by itself. For example in XWiki Syntax 2.0+ this means having 2 newline characters (a.k.a line breaks) separating your macro from the content before and after it. 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 The [diagram] macro is a standalone macro and it cannot be used inline. Click on this message for details.
  This macro generates standalone content. As a consequence you need to make sure to use a syntax that separates your macro from the content before and after it so that it's on a line by itself. For example in XWiki Syntax 2.0+ this means having 2 newline characters (a.k.a line breaks) separating your macro from the content before and after it. 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 The [diagram] macro is a standalone macro and it cannot be used inline. Click on this message for details.
  This macro generates standalone content. As a consequence you need to make sure to use a syntax that separates your macro from the content before and after it so that it's on a line by itself. For example in XWiki Syntax 2.0+ this means having 2 newline characters (a.k.a line breaks) separating your macro from the content before and after it. 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 The [diagram] macro is a standalone macro and it cannot be used inline. Click on this message for details.
  This macro generates standalone content. As a consequence you need to make sure to use a syntax that separates your macro from the content before and after it so that it's on a line by itself. For example in XWiki Syntax 2.0+ this means having 2 newline characters (a.k.a line breaks) separating your macro from the content before and after it. === 2.2 Gate Implementation by Phase === |=Gate|=POC1|=POC2|=Beta 0|=V1.0

• 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