Skip to Content

Wiki source code of System Architecture

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