Skip to Content

Wiki source code of Architecture

Last modified by Robert Schaub on 2026/02/08 08:22
Show last authors
1 = Architecture =
2
3 FactHarbor uses a modular-monolith architecture (POC → Beta 0) designed to evolve into a distributed, federated, multi-node system (Release 1.0+).
4 Modules are strongly separated, versioned, and auditable. All logic is transparent and deterministic.
5
6
7 = High-Level System Architecture =
8
9 FactHarbor is composed of the following major modules:
10
11 * **UI Frontend**
12 * **REST API Layer**
13 * **Core Logic Layer**
14 ** Claim Processing
15 ** Scenario Engine
16 ** Evidence Repository
17 ** Verdict Engine
18 ** Re-evaluation Engine
19 ** Roles / Identity / Reputation
20 * **AKEL (AI Knowledge Extraction Layer)**
21 * **Federation Layer**
22 * **Workers & Background Jobs**
23 * **Storage Layer (Postgres + VectorDB + ObjectStore)**
24
25 {{include reference="Archive.FactHarbor 2026\.01\.20.Specification.Diagrams.High-Level Architecture.WebHome"/}}
26
27 Key ideas:
28
29 * Core logic is deterministic, auditable, and versioned 
30 * AKEL drafts structured outputs but never publishes directly 
31 * Workers run long or asynchronous tasks 
32 * Storage is separated for scalability and clarity 
33 * Federation Layer provides optional distributed operation 
34
35 = Storage Architecture =
36
37 FactHarbor separates structured data, embeddings, and evidence files:
38
39 * **PostgreSQL** — canonical structured entities, all versioning, lineage, signatures 
40 * **Vector DB (Qdrant or pgvector)** — semantic search, duplication detection, cluster mapping 
41 * **Object Storage** — PDFs, datasets, raw evidence, transcripts 
42 * **Optional (Release 1.0)**: Redis for caching, IPFS for decentralized object storage 
43
44 {{include reference="Archive.FactHarbor 2026\.01\.20.Specification.Diagrams.Storage Architecture.WebHome"/}}
45
46
47 = Core Backend Module Architecture =
48
49 Each module has a clear responsibility and versioned boundaries to allow future extraction into microservices.
50
51 == 1. Claim Processing Module ==
52
53 Responsibilities:
54
55 * Ingest text, URLs, documents, transcripts, federated input 
56 * Extract claims (AKEL-assisted) 
57 * Normalize structure 
58 * Classify (type, domain, evaluability, safety) 
59 * Deduplicate via embeddings 
60 * Assign to claim clusters 
61
62 Flow:
63 **Ingest → Normalize → Classify → Deduplicate → Cluster**
64
65
66 == 2. Scenario Engine ==
67
68 Responsibilities:
69
70 * Create and validate scenarios 
71 * Enforce required fields (definitions, assumptions, boundaries...) 
72 * Perform safety checks (AKEL-assisted) 
73 * Manage versioning and lifecycle 
74 * Provide contextual evaluation settings to the Verdict Engine 
75
76 Flow:
77 **Create → Validate → Version → Lifecycle → Safety**
78
79
80 == 3. Evidence Repository ==
81
82 Responsibilities:
83
84 * Store metadata + files (object store) 
85 * Classify evidence 
86 * Compute preliminary reliability 
87 * Maintain version history 
88 * Detect retractions or disputes 
89 * Provide structured metadata to the Verdict Engine 
90
91 Flow:
92 **Store → Classify → Score → Version → Update/Retract**
93
94
95 == 4. Verdict Engine ==
96
97 Responsibilities:
98
99 * Aggregate scenario-linked evidence 
100 * Compute likelihood ranges **per scenario**
101 * Generate reasoning chain 
102 * Track uncertainty factors 
103 * Maintain verdict version timelines 
104
105 Flow:
106 **Aggregate → Compute → Explain → Version → Timeline**
107
108
109 == 5. Re-evaluation Engine ==
110
111 Responsibilities:
112
113 * Listen for upstream changes 
114 * Trigger partial or full recomputation 
115 * Update verdicts + summary views 
116 * Maintain consistency across federated nodes 
117
118 Triggers include:
119
120 * Evidence updated or retracted 
121 * Scenario definition or assumption changes 
122 * Claim type or evaluability changes 
123 * Contradiction detection 
124 * Federation sync updates 
125
126 Flow:
127 **Trigger → Impact Analysis → Recompute → Publish Update**
128
129
130 = AKEL Integration Summary =
131
132 AKEL is fully documented in its own chapter.
133 Here is only the architectural integration summary:
134
135 * Receives raw input for claims 
136 * Proposes scenario drafts 
137 * Extracts and summarizes evidence 
138 * Gives reliability hints 
139 * Suggests draft verdicts 
140 * Monitors contradictions 
141 * Syncs metadata with trusted nodes 
142
143 AKEL runs in parallel to human review — never overrides it.
144
145 {{include reference="Archive.FactHarbor 2026\.01\.20.Specification.Diagrams.AKEL Architecture.WebHome"/}}
146
147
148 = Federated Architecture =
149
150 Each FactHarbor node:
151
152 * Has its own dataset (claims, scenarios, evidence, verdicts) 
153 * Runs its own AKEL 
154 * Maintains local governance and reviewer rules 
155 * May partially mirror global or domain-specific data 
156 * Contributes to global knowledge clusters 
157
158 Nodes synchronize via:
159
160 * Signed version bundles 
161 * Merkle-tree lineage structures 
162 * Optionally IPFS for evidence 
163 * Trust-weighted acceptance 
164
165 Benefits:
166
167 * Community independence 
168 * Scalability 
169 * Resilience 
170 * Domain specialization 
171
172 {{include reference="Archive.FactHarbor 2026\.01\.20.Specification.Diagrams.Federation Architecture.WebHome"/}}
173
174
175 = Request → Verdict Flow =
176
177 Simple end-to-end flow:
178
179 **User → UI Frontend → REST API → FactHarbor Core
180 → (Claim Processing → Scenario Engine → Evidence Repository → Verdict Engine)
181 → Summary View → UI Frontend → User**
182
183
184 = Federation Sync Workflow =
185
186 Sequence:
187
188 **Detect Local Change → Build Signed Bundle → Push to Peers → Validate Signature → Merge or Fork → Trigger Re-evaluation**
189
190
191 = Versioning Architecture =
192
193 All entities (Claim, Scenario, Evidence, Verdict) use immutable version chains:
194
195 * VersionID 
196 * ParentVersionID 
197 * Timestamp 
198 * AuthorType (Human, AI, ExternalNode) 
199 * ChangeReason 
200 * Signature (optional POC, required in 1.0) 
201
202 {{include reference="Archive.FactHarbor 2026\.01\.20.Specification.Diagrams.Versioning Architecture.WebHome"/}}