Skip to Content

Wiki source code of System Architecture

Version 1.1 by Robert Schaub on 2025/12/21 11:25
Show last authors
1 = System Architecture =
2
3 **FactHarbor system architecture including POC simplifications and full system design**
4
5 ---
6
7 == 1. Architecture Evolution ==
8
9 FactHarbor will be built in phases, with architecture complexity increasing as we validate core capabilities.
10
11 === 1.1 POC1 Architecture (Simplified) ===
12
13 **Goal:** Validate core AI capability with minimal complexity
14
15 {{diagram}}
16 ┌─────────────┐
17 │ User Input │
18 │ (Text/URL) │
19 └──────┬──────┘
20 │
21 ▼
22 ┌─────────────────────┐
23 │ AKEL Processing │
24 │ ┌─────────────────┐ │
25 │ │ Claim Extraction│ │
26 │ └────────┬────────┘ │
27 │ ▼ │
28 │ ┌─────────────────┐ │
29 │ │ Verdict │ │
30 │ │ Generation │ │
31 │ └────────┬────────┘ │
32 └──────────┼──────────┘
33 │
34 ▼
35 ┌──────────────┐
36 │ Quality Gates│
37 │ (Gates 1 & 4)│
38 └──────┬───────┘
39 │
40 ┌─────┴─────┐
41 │ Pass? │
42 └─┬───────┬─┘
43 YES │ │ NO
44 ▼ ▼
45 ┌─────┐ ┌──────────┐
46 │Show │ │ Block │
47 │User │ │+ Explain │
48 └─────┘ └──────────┘
49 {{/diagram}}
50
51 **Components:**
52 * Single AKEL API call (Claude Sonnet 4.5)
53 * Gates 1 & 4 (claim validation, verdict confidence)
54 * Basic UI display
55 * Manual quality tracking
56
57 **Data Storage:** Minimal (stateless or simple SQLite)
58
59 ---
60
61 === 1.2 POC2 Architecture (Enhanced) ===
62
63 **Goal:** Add complete quality framework and evidence deduplication
64
65 {{diagram}}
66 ┌─────────────┐
67 │ User Input │
68 └──────┬──────┘
69 │
70 ▼
71 ┌──────────────────────────┐
72 │ Enhanced AKEL │
73 │ ┌──────────────────────┐ │
74 │ │ Claim Extraction │ │
75 │ └──────┬───────────────┘ │
76 │ ▼ │
77 │ ┌──────────────────────┐ │
78 │ │ Scenario Generation │ │
79 │ └──────┬───────────────┘ │
80 │ ▼ │
81 │ ┌──────────────────────┐ │
82 │ │ Evidence Linking │ │
83 │ │ + Deduplication │ │
84 │ └──────┬───────────────┘ │
85 │ ▼ │
86 │ ┌──────────────────────┐ │
87 │ │ Verdict Generation │ │
88 │ └──────┬───────────────┘ │
89 └────────┼──────────────────┘
90 │
91 ▼
92 ┌──────────────────┐
93 │ All Quality Gates│
94 │ (Gates 1-4) │
95 └────────┬─────────┘
96 │
97 ▼
98 ┌─────────────┐
99 │ Display │
100 │+ Metrics │
101 └─────────────┘
102 {{/diagram}}
103
104 **New Components:**
105 * Scenario generation
106 * Evidence deduplication system
107 * Gates 2 & 3 (evidence relevance, scenario coherence)
108 * Quality metrics dashboard
109
110 **Data Storage:** Enhanced (claims, scenarios, evidence, metrics)
111
112 ---
113
114 === 1.3 Full System Architecture (V1.0+) ===
115
116 **Goal:** Production-ready multi-component system
117
118 {{diagram}}
119 ┌────────────────────┐
120 │ Input Layer │
121 │ API / UI / Bot │
122 └─────────┬──────────┘
123 │
124 ▼
125 ┌─────────────────────────────────────┐
126 │ AKEL Orchestrator │
127 │ ┌─────────────────────────────────┐ │
128 │ │ Component Pipeline: │ │
129 │ │ 1. Claim Extractor │ │
130 │ │ 2. Claim Classifier │ │
131 │ │ 3. Scenario Generator │ │
132 │ │ 4. Evidence Summarizer │ │
133 │ │ 5. Contradiction Detector │ │
134 │ │ 6. Verdict Generator │ │
135 │ └─────────────────────────────────┘ │
136 └──────────────┬──────────────────────┘
137 │
138 ▼
139 ┌──────────────┐
140 │Quality Gates │
141 │(All 4 Gates) │
142 └──────┬───────┘
143 │
144 ┌─────┴─────┐
145 │Publication│
146 │ Decision │
147 └─┬───────┬─┘
148 AI │ │ Review
149 Ready │ │ Needed
150 ▼ ▼
151 ┌────────┐ ┌───────────┐
152 │ Public │ │Review │
153 │Display │ │Queue │
154 └────────┘ │(Human) │
155 └─────┬─────┘
156 │
157 ▼
158 ┌──────────┐
159 │ Publish │
160 └──────────┘
161 {{/diagram}}
162
163 **Production Components:**
164 * Multi-component AKEL pipeline
165 * Review workflow system
166 * Audit sampling framework
167 * Federation architecture
168 * Full data model (PostgreSQL + Redis + S3)
169
170 ---
171
172 == 2. Quality Gate Architecture ==
173
174 === 2.1 Quality Gate System ===
175
176 **Purpose:** Prevent low-quality/hallucinated content from publication
177
178 {{diagram}}
179 Quality Gate Pipeline:
180
181 Claim/Verdict Input
182 │
183 ▼
184 ┌─────────────────┐
185 │ Gate 1: │ Validates claim is factual
186 │ Claim Validation│ (not opinion/prediction)
187 └────────┬────────┘
188 │ PASS
189 ▼
190 ┌─────────────────┐
191 │ Gate 2: │ Validates evidence relates
192 │ Evidence │ to claim (semantic matching)
193 │ Relevance │
194 └────────┬────────┘
195 │ PASS
196 ▼
197 ┌─────────────────┐
198 │ Gate 3: │ Validates scenario logic
199 │ Scenario │ and completeness
200 │ Coherence │
201 └────────┬────────┘
202 │ PASS
203 ▼
204 ┌─────────────────┐
205 │ Gate 4: │ Validates sufficient
206 │ Verdict │ evidence + confidence
207 │ Confidence │
208 └────────┬────────┘
209 │ PASS
210 ▼
211 Publication
212
213 (Any gate FAIL → Block + Explain)
214 {{/diagram}}
215
216 ---
217
218 === 2.2 Gate Implementation by Phase ===
219
220 |=Gate|=POC1|=POC2|=Beta 0|=V1.0
221 |Gate 1: Claim Validation|✅ Basic|✅ Enhanced|✅ Enhanced|✅ Hardened
222 |Gate 2: Evidence Relevance|❌|✅ Implemented|✅ Enhanced|✅ Hardened
223 |Gate 3: Scenario Coherence|❌|✅ Implemented|✅ Enhanced|✅ Hardened
224 |Gate 4: Verdict Confidence|✅ Basic|✅ Enhanced|✅ Enhanced|✅ Hardened
225
226 **Hardening** means: Thresholds validated, edge cases handled, <5% failure rate
227
228 ---
229
230 == 3. Data Architecture ==
231
232 === 3.1 POC Data Model (Simplified) ===
233
234 **Storage:** SQLite or minimal database
235
236 **Entities:**
237 * Articles (input text/URL)
238 * Claims (extracted from articles)
239 * Verdicts (per claim)
240 * Quality metrics (aggregated)
241
242 **No complex relationships, versioning, or scenarios**
243
244 ---
245
246 === 3.2 Full System Data Model (V1.0+) ===
247
248 **Storage:** PostgreSQL (primary), Redis (cache), S3 (documents)
249
250 **Core Entities:**
251 * Claims (with versions, clustering)
252 * Scenarios (interpretations of claims)
253 * Evidence (deduplicated, provenance tracked)
254 * Verdicts (per scenario, versioned)
255 * Reviews (human oversight)
256 * Quality metrics (per component, aggregated)
257
258 **Complex relationships, full audit trail, federation support**
259
260 ---
261
262 == 4. Component Architecture ==
263
264 === 4.1 AKEL Orchestrator ===
265
266 **POC:** Single API call
267 **Full System:** Multi-component orchestration
268
269 **Responsibilities:**
270 * Route input through component pipeline
271 * Manage component state
272 * Handle errors and retries
273 * Coordinate quality gates
274 * Trigger review workflows
275
276 ---
277
278 === 4.2 Quality Gate Validator ===
279
280 **All Phases:** Present but evolving complexity
281
282 **Responsibilities:**
283 * Execute all configured gates
284 * Aggregate gate results
285 * Make publication decisions
286 * Generate explanatory messages
287 * Log quality metrics
288
289 ---
290
291 === 4.3 Review Queue Manager ===
292
293 **POC:** Not present
294 **Beta 0+:** Optional
295 **V1.0:** Full implementation
296
297 **Responsibilities:**
298 * Route low-confidence verdicts to review
299 * Manage reviewer assignments
300 * Track review status
301 * Implement audit sampling
302 * Generate review metrics
303
304 ---
305
306 == 5. Architecture Decisions ==
307
308 === 5.1 Why Single AKEL Call for POC? ===
309
310 **Rationale:**
311 * Validates core capability fastest
312 * Simplest to implement and test
313 * Fail-fast if AI fundamentally can't do task
314 * Learn prompt engineering before architecting components
315 * Reduce moving parts during initial testing
316
317 **Trade-off:** Less granular control, harder to optimize individual steps
318
319 ---
320
321 === 5.2 Why Add Components in V1.0? ===
322
323 **Rationale:**
324 * Better error handling per step
325 * Independent optimization of each component
326 * Easier to add new capabilities
327 * Better observability and debugging
328 * Supports federation (multiple FactHarbor instances)
329
330 **Trade-off:** More complexity, more to maintain
331
332 ---
333
334 == 6. Related Pages ==
335
336 * [[Requirements>>Test.FactHarbor.Specification.Requirements.WebHome]] - System requirements
337 * [[Design>>Test.FactHarbor.Specification.Design.WebHome]] - UI/UX design
338 * [[Roadmap>>Test.FactHarbor.Roadmap.WebHome]] - Implementation phases
339 * [[POC1>>Test.FactHarbor.Roadmap.POC1.WebHome]] - POC1 details
340 * [[POC2>>Test.FactHarbor.Roadmap.POC2.WebHome]] - POC2 details
341
342 ---
343
344 **Document Status:** ✅ Architecture Specified (POC1, POC2, Full System)
345 **Version:** V0.9.70