Skip to Content

Wiki source code of System Architecture

Version 1.1 by Robert Schaub on 2025/12/22 14:10
Show last authors
1 = 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 {{diagram}}
2 ┌─────────────┐
3 │ User Input │
4 │ (Text/URL) │
5 └──────┬──────┘ │ ▼
6 ┌─────────────────────┐
7 │ AKEL Processing │
8 │ ┌─────────────────┐ │
9 │ │ Claim Extraction│ │
10 │ └────────┬────────┘ │
11 │ ▼ │
12 │ ┌─────────────────┐ │
13 │ │ Verdict │ │
14 │ │ Generation │ │
15 │ └────────┬────────┘ │
16 └──────────┼──────────┘ │ ▼ ┌──────────────┐ │ Quality Gates│ │ (Gates 1 & 4)│ └──────┬───────┘ │ ┌─────┴─────┐ │ Pass? │ └─┬───────┬─┘ YES │ │ NO ▼ ▼ ┌─────┐ ┌──────────┐ │Show │ │ Block │ │User │ │+ Explain │ └─────┘ └──────────┘
17 {{/diagram}} **Components:**
18 * Single AKEL API call (Claude Sonnet 4.5)
19 * Gates 1 & 4 (claim validation, verdict confidence)
20 * Basic UI display
21 * Manual quality tracking **Data Storage:** Minimal (stateless or simple SQLite) === 1.2 POC2 Architecture (Enhanced) === **Goal:** Add complete quality framework and evidence deduplication {{diagram}}
22 ┌─────────────┐
23 │ User Input │
24 └──────┬──────┘ │ ▼
25 ┌──────────────────────────┐
26 │ Enhanced AKEL │
27 │ ┌──────────────────────┐ │
28 │ │ Claim Extraction │ │
29 │ └──────┬───────────────┘ │
30 │ ▼ │
31 │ ┌──────────────────────┐ │
32 │ │ Scenario Generation │ │
33 │ └──────┬───────────────┘ │
34 │ ▼ │
35 │ ┌──────────────────────┐ │
36 │ │ Evidence Linking │ │
37 │ │ + Deduplication │ │
38 │ └──────┬───────────────┘ │
39 │ ▼ │
40 │ ┌──────────────────────┐ │
41 │ │ Verdict Generation │ │
42 │ └──────┬───────────────┘ │
43 └────────┼──────────────────┘ │ ▼ ┌──────────────────┐ │ All Quality Gates│ │ (Gates 1-4) │ └────────┬─────────┘ │ ▼ ┌─────────────┐ │ Display │ │+ Metrics │ └─────────────┘
44 {{/diagram}} **New Components:**
45 * Scenario generation
46 * Evidence deduplication system
47 * Gates 2 & 3 (evidence relevance, scenario coherence)
48 * Quality metrics dashboard **Data Storage:** Enhanced (claims, scenarios, evidence, metrics) === 1.3 Full System Architecture (V1.0+) === **Goal:** Production-ready multi-component system {{diagram}}
49 ┌────────────────────┐
50 │ Input Layer │
51 │ API / UI / Bot │
52 └─────────┬──────────┘ │ ▼
53 ┌─────────────────────────────────────┐
54 │ AKEL Orchestrator │
55 │ ┌─────────────────────────────────┐ │
56 │ │ Component Pipeline: │ │
57 │ │ 1. Claim Extractor │ │
58 │ │ 2. Claim Classifier │ │
59 │ │ 3. Scenario Generator │ │
60 │ │ 4. Evidence Summarizer │ │
61 │ │ 5. Contradiction Detector │ │
62 │ │ 6. Verdict Generator │ │
63 │ └─────────────────────────────────┘ │
64 └──────────────┬──────────────────────┘ │ ▼ ┌──────────────┐ │Quality Gates │ │(All 4 Gates) │ └──────┬───────┘ │ ┌─────┴─────┐ │Publication│ │ Decision │ └─┬───────┬─┘ AI │ │ Review Ready │ │ Needed ▼ ▼ ┌────────┐ ┌───────────┐ │ Public │ │Review │ │Display │ │Queue │ └────────┘ │(Human) │ └─────┬─────┘ │ ▼ ┌──────────┐ │ Publish │ └──────────┘
65 {{/diagram}} **Production Components:**
66 * Multi-component AKEL pipeline
67 * Review workflow system
68 * Audit sampling framework
69 * Federation architecture
70 * Full data model (PostgreSQL + Redis + S3) == 2. Quality Gate Architecture == === 2.1 Quality Gate System === **Purpose:** Prevent low-quality/hallucinated content from publication {{diagram}}
71 Quality Gate Pipeline: Claim/Verdict Input │ ▼
72 ┌─────────────────┐
73 │ Gate 1: │ Validates claim is factual
74 │ Claim Validation│ (not opinion/prediction)
75 └────────┬────────┘ │ PASS ▼
76 ┌─────────────────┐
77 │ Gate 2: │ Validates evidence relates
78 │ Evidence │ to claim (semantic matching)
79 │ Relevance │
80 └────────┬────────┘ │ PASS ▼
81 ┌─────────────────┐
82 │ Gate 3: │ Validates scenario logic
83 │ Scenario │ and completeness
84 │ Coherence │
85 └────────┬────────┘ │ PASS ▼
86 ┌─────────────────┐
87 │ Gate 4: │ Validates sufficient
88 │ Verdict │ evidence + confidence
89 │ Confidence │
90 └────────┬────────┘ │ PASS ▼ Publication (Any gate FAIL → Block + Explain)
91 {{/diagram}} === 2.2 Gate Implementation by Phase === |=Gate|=POC1|=POC2|=Beta 0|=V1.0
92 |Gate 1: Claim Validation|✅ Basic|✅ Enhanced|✅ Enhanced|✅ Hardened
93 |Gate 2: Evidence Relevance|❌|✅ Implemented|✅ Enhanced|✅ Hardened
94 |Gate 3: Scenario Coherence|❌|✅ Implemented|✅ Enhanced|✅ Hardened
95 |Gate 4: Verdict Confidence|✅ Basic|✅ Enhanced|✅ Enhanced|✅ Hardened **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:**
96 * Articles (input text/URL)
97 * Claims (extracted from articles)
98 * Verdicts (per claim)
99 * 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:**
100 * Claims (with versions, clustering)
101 * Scenarios (interpretations of claims)
102 * Evidence (deduplicated, provenance tracked)
103 * Verdicts (per scenario, versioned)
104 * Reviews (human oversight)
105 * 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:**
106 * Route input through component pipeline
107 * Manage component state
108 * Handle errors and retries
109 * Coordinate quality gates
110 * Trigger review workflows === 4.2 Quality Gate Validator === **All Phases:** Present but evolving complexity **Responsibilities:**
111 * Execute all configured gates
112 * Aggregate gate results
113 * Make publication decisions
114 * Generate explanatory messages
115 * Log quality metrics === 4.3 Review Queue Manager === **POC:** Not present **Beta 0+:** Optional **V1.0:** Full implementation **Responsibilities:**
116 * Route low-confidence verdicts to review
117 * Manage reviewer assignments
118 * Track review status
119 * Implement audit sampling
120 * Generate review metrics == 5. Architecture Decisions == === 5.1 Why Single AKEL Call for POC? === **Rationale:**
121 * Validates core capability fastest
122 * Simplest to implement and test
123 * Fail-fast if AI fundamentally can't do task
124 * Learn prompt engineering before architecting components
125 * 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:**
126 * Better error handling per step
127 * Independent optimization of each component
128 * Easier to add new capabilities
129 * Better observability and debugging
130 * Supports federation (multiple FactHarbor instances) **Trade-off:** More complexity, more to maintain == 6. Related Pages == * [[Requirements>>Test.FactHarbor.Specification.Requirements.WebHome]] - System requirements
131 * [[Design>>Test.FactHarbor.Specification.Design.WebHome]] - UI/UX design
132 * [[Roadmap>>Test.FactHarbor.Roadmap.WebHome]] - Implementation phases
133 * [[POC1>>Test.FactHarbor.Roadmap.POC1.WebHome]] - POC1 details
134 * [[POC2>>Test.FactHarbor.Roadmap.POC2.WebHome]] - POC2 details **Document Status:** ✅ Architecture Specified (POC1, POC2, Full System) **Version:** V0.9.70