Skip to Content

Wiki source code of Architecture

Version 3.1 by Robert Schaub on 2025/12/11 21:35
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"/}}