Skip to Content

Wiki source code of System Architecture

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