Skip to Content

Wiki source code of System Architecture

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