Skip to Content

Wiki source code of Architecture

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