Skip to Content

Changes for page Architecture

Last modified by Robert Schaub on 2025/12/24 20:34
From version 4.1
edited by Robert Schaub
on 2025/12/12 08:32
Change comment: Imported from XAR
To version 6.2
edited by Robert Schaub
on 2025/12/16 20:25
Change comment: Update document after refactoring.

Summary

Details

Page properties
Parent
... ... @@ -1,1 +1,1 @@
1 -FactHarbor.Specification.WebHome
1 +FactHarbor.Archive.FactHarbor.Specification.WebHome
Content
... ... @@ -3,18 +3,20 @@
3 3  FactHarbor uses a modular-monolith architecture (POC → Beta 0) designed to evolve into a distributed, federated, multi-node system (Release 1.0+).
4 4  Modules are strongly separated, versioned, and auditable. All logic is transparent and deterministic.
5 5  
6 -== High-Level System Architecture ==
6 +----
7 7  
8 += High-Level System Architecture =
9 +
8 8  FactHarbor is composed of the following major modules:
9 9  
10 10  * **UI Frontend**
11 11  * **REST API Layer**
12 12  * **Core Logic Layer**
13 -** Claim Processing
14 -** Scenario Engine
15 -** Evidence Repository
16 -** Verdict Engine
17 -** Re-evaluation Engine
15 +** Claim Processing
16 +** Scenario Engine
17 +** Evidence Repository
18 +** Verdict Engine
19 +** Re-evaluation Engine
18 18  ** Roles / Identity / Reputation
19 19  * **AKEL (AI Knowledge Extraction Layer)**
20 20  * **Federation Layer**
... ... @@ -21,174 +21,195 @@
21 21  * **Workers & Background Jobs**
22 22  * **Storage Layer (Postgres + VectorDB + ObjectStore)**
23 23  
24 -{{include reference="FactHarbor.Specification.Diagrams.High-Level Architecture.WebHome"/}}
26 +{{include reference="Test.FactHarborV09.Specification.Diagrams.High-Level Architecture.WebHome"/}}
25 25  
26 26  Key ideas:
27 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.
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 
33 33  
34 -== Storage Architecture ==
36 +----
35 35  
38 += Storage Architecture =
39 +
36 36  FactHarbor separates structured data, embeddings, and evidence files:
37 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 +* **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 
42 42  
43 -{{include reference="FactHarbor.Specification.Diagrams.Storage Architecture.WebHome"/}}
47 +{{include reference="Test.FactHarborV09.Specification.Diagrams.Storage Architecture.WebHome"/}}
44 44  
45 -== Core Backend Module Architecture ==
49 +----
46 46  
51 += Core Backend Module Architecture =
52 +
47 47  Each module has a clear responsibility and versioned boundaries to allow future extraction into microservices.
48 48  
49 -=== Claim Processing Module ===
55 +== Claim Processing Module ==
50 50  
51 51  Responsibilities:
52 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 +* 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 
59 59  
60 -Flow: **Ingest → Normalize → Classify → Deduplicate → Cluster**
66 +Flow:
67 +**Ingest → Normalize → Classify → Deduplicate → Cluster**
61 61  
62 -=== Scenario Engine ===
69 +----
63 63  
71 +== Scenario Engine ==
72 +
64 64  Responsibilities:
65 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
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 
71 71  
72 -Flow: **Create → Validate → Version → Lifecycle → Safety**
81 +Flow:
82 +**Create → Validate → Version → Lifecycle → Safety**
73 73  
74 -=== Evidence Repository ===
84 +----
75 75  
86 +== Evidence Repository ==
87 +
76 76  Responsibilities:
77 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
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 
84 84  
85 -Flow: **Store → Classify → Score → Version → Update/Retract**
97 +Flow:
98 +**Store → Classify → Score → Version → Update/Retract**
86 86  
87 -=== Verdict Engine ===
100 +----
88 88  
102 +== Verdict Engine ==
103 +
89 89  Responsibilities:
90 90  
91 -* Aggregate scenario-linked evidence
106 +* Aggregate scenario-linked evidence 
92 92  * Compute likelihood ranges **per scenario**
93 -* Generate reasoning chain
94 -* Track uncertainty factors
95 -* Maintain verdict version timelines
108 +* Generate reasoning chain 
109 +* Track uncertainty factors 
110 +* Maintain verdict version timelines 
96 96  
97 -Flow: **Aggregate → Compute → Explain → Version → Timeline**
112 +Flow:
113 +**Aggregate → Compute → Explain → Version → Timeline**
98 98  
99 -=== Re-evaluation Engine ===
115 +----
100 100  
117 +== Re-evaluation Engine ==
118 +
101 101  Responsibilities:
102 102  
103 -* Listen for upstream changes
104 -* Trigger partial or full recomputation
105 -* Update verdicts + summary views
106 -* Maintain consistency across federated nodes
121 +* Listen for upstream changes 
122 +* Trigger partial or full recomputation 
123 +* Update verdicts + summary views 
124 +* Maintain consistency across federated nodes 
107 107  
108 108  Triggers include:
109 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
128 +* Evidence updated or retracted 
129 +* Scenario definition or assumption changes 
130 +* Claim type or evaluability changes 
131 +* Contradiction detection 
132 +* Federation sync updates 
115 115  
116 -Flow: **Trigger → Impact Analysis → Recompute → Publish Update**
134 +Flow:
135 +**Trigger → Impact Analysis → Recompute → Publish Update**
117 117  
118 -== AKEL Integration Summary ==
137 +----
119 119  
120 -AKEL is fully documented in its own chapter. Here is only the architectural integration summary:
139 += AKEL Integration Summary =
121 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
141 +AKEL is fully documented in its own chapter.
142 +Here is only the architectural integration summary:
129 129  
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 +
130 130  AKEL runs in parallel to human review — never overrides it.
131 131  
132 -{{include reference="FactHarbor.Specification.Diagrams.AKEL Architecture.WebHome"/}}
154 +{{include reference="Test.FactHarborV09.Specification.Diagrams.AKEL Architecture.WebHome"/}}
133 133  
134 -== Federated Architecture ==
156 +----
135 135  
158 += Federated Architecture =
159 +
136 136  Each FactHarbor node:
137 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
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 
143 143  
144 144  Nodes synchronize via:
145 145  
146 -* Signed version bundles
147 -* Merkle-tree lineage structures
148 -* Optionally IPFS for evidence
149 -* Trust-weighted acceptance
170 +* Signed version bundles 
171 +* Merkle-tree lineage structures 
172 +* Optionally IPFS for evidence 
173 +* Trust-weighted acceptance 
150 150  
151 151  Benefits:
152 152  
153 -* Community independence
154 -* Scalability
155 -* Resilience
156 -* Domain specialization
177 +* Community independence 
178 +* Scalability 
179 +* Resilience 
180 +* Domain specialization 
157 157  
158 -{{include reference="FactHarbor.Specification.Diagrams.Federation Architecture.WebHome"/}}
182 +{{include reference="Test.FactHarborV09.Specification.Diagrams.Federation Architecture.WebHome"/}}
159 159  
160 -== Request → Verdict Flow ==
184 +----
161 161  
186 += Request → Verdict Flow =
187 +
162 162  Simple end-to-end flow:
163 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
190 +**User → UI Frontend → REST API → FactHarbor Core
191 + → (Claim Processing → Scenario Engine → Evidence Repository → Verdict Engine)
192 + → Summary View → UI Frontend → User**
171 171  
172 -== Federation Sync Workflow ==
173 173  
195 +----
196 +
197 += Federation Sync Workflow =
198 +
174 174  Sequence:
175 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
201 +**Detect Local Change → Build Signed Bundle → Push to Peers → Validate Signature → Merge or Fork → Trigger Re-evaluation**
182 182  
183 -== Versioning Architecture ==
184 184  
204 +----
205 +
206 += Versioning Architecture =
207 +
185 185  All entities (Claim, Scenario, Evidence, Verdict) use immutable version chains:
186 186  
187 -* VersionID
188 -* ParentVersionID
189 -* Timestamp
190 -* AuthorType (Human, AI, ExternalNode)
191 -* ChangeReason
192 -* Signature (optional POC, required in 1.0)
210 +* VersionID 
211 +* ParentVersionID 
212 +* Timestamp 
213 +* AuthorType (Human, AI, ExternalNode) 
214 +* ChangeReason 
215 +* Signature (optional POC, required in 1.0) 
193 193  
194 -{{include reference="FactHarbor.Specification.Diagrams.Versioning Architecture.WebHome"/}}
217 +{{include reference="Test.FactHarborV09.Specification.Diagrams.Versioning Architecture.WebHome"/}}