Skip to Content

Wiki source code of Architecture

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