Wiki source code of System Architecture

Last modified by Robert Schaub on 2025/12/24 20:35

version	line-number	content
1.1	1	= System Architecture =
	2
	3	FactHarbor system architecture including POC simplifications and full system design
	4
1.3	5	----
1.1	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:
1.2	52
1.1	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
1.3	60	----
1.1	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:
1.2	106
1.1	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
1.3	114	----
1.1	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:
1.2	166
1.1	167	* Multi-component AKEL pipeline
	168	* Review workflow system
	169	* Audit sampling framework
	170	* Federation architecture
	171	* Full data model (PostgreSQL + Redis + S3)
	172
1.3	173	----
1.1	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
1.3	219	----
1.1	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
1.3	231	----
1.1	232
	233	== 3. Data Architecture ==
	234
	235	=== 3.1 POC Data Model (Simplified) ===
	236
	237	Storage: SQLite or minimal database
	238
	239	Entities:
1.2	240
1.1	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
1.3	248	----
1.1	249
	250	=== 3.2 Full System Data Model (V1.0+) ===
	251
	252	Storage: PostgreSQL (primary), Redis (cache), S3 (documents)
	253
	254	Core Entities:
1.2	255
1.1	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
1.3	265	----
1.1	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:
1.2	275
1.1	276	* Route input through component pipeline
	277	* Manage component state
	278	* Handle errors and retries
	279	* Coordinate quality gates
	280	* Trigger review workflows
	281
1.3	282	----
1.1	283
	284	=== 4.2 Quality Gate Validator ===
	285
	286	All Phases: Present but evolving complexity
	287
	288	Responsibilities:
1.2	289
1.1	290	* Execute all configured gates
	291	* Aggregate gate results
	292	* Make publication decisions
	293	* Generate explanatory messages
	294	* Log quality metrics
	295
1.3	296	----
1.1	297
	298	=== 4.3 Review Queue Manager ===
	299
	300	POC: Not present
	301	Beta 0+: Optional
	302	V1.0: Full implementation
	303
	304	Responsibilities:
1.2	305
1.1	306	* Route low-confidence verdicts to review
	307	* Manage reviewer assignments
	308	* Track review status
	309	* Implement audit sampling
	310	* Generate review metrics
	311
1.3	312	----
1.1	313
	314	== 5. Architecture Decisions ==
	315
	316	=== 5.1 Why Single AKEL Call for POC? ===
	317
	318	Rationale:
1.2	319
1.1	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
1.3	328	----
1.1	329
	330	=== 5.2 Why Add Components in V1.0? ===
	331
	332	Rationale:
1.2	333
1.1	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
1.3	342	----
1.1	343
	344	== 6. Related Pages ==
	345
1.13	346	* [[Requirements>>Archive.FactHarbor delta for V0\.9\.70.Specification.Requirements.WebHome]] - System requirements
1.12	347	* [[Design>>Archive.FactHarbor delta for V0\.9\.70.Specification.Design.WebHome]] - UI/UX design
1.10	348	* [[Roadmap>>Archive.FactHarbor delta for V0\.9\.70.Roadmap.WebHome]] - Implementation phases
1.8	349	* [[POC1>>Archive.FactHarbor delta for V0\.9\.70.Roadmap.POC1.WebHome]] - POC1 details
1.9	350	* [[POC2>>Archive.FactHarbor delta for V0\.9\.70.Roadmap.POC2.WebHome]] - POC2 details
1.1	351
1.3	352	----
1.1	353
	354	Document Status: ✅ Architecture Specified (POC1, POC2, Full System)
	355	Version: V0.9.70