Skip to Content

Wiki source code of System Architecture

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