Skip to Content

Wiki source code of Architecture

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