Wiki source code of Architecture
Last modified by Robert Schaub on 2025/12/24 20:34
Hide last authors
| author | version | line-number | content |
|---|---|---|---|
 |
1.1 | 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 | |||
| |
5.1 | 6 | ---- |
| |
1.1 | 7 | |
| |
5.1 | 8 | = High-Level System Architecture = |
| 9 | |||
| |
1.1 | 10 | FactHarbor is composed of the following major modules: |
| 11 | |||
| 12 | * **UI Frontend** | ||
| 13 | * **REST API Layer** | ||
| 14 | * **Core Logic Layer** | ||
| |
5.1 | 15 | ** Claim Processing |
| 16 | ** Scenario Engine | ||
| 17 | ** Evidence Repository | ||
| 18 | ** Verdict Engine | ||
| 19 | ** Re-evaluation Engine | ||
| |
4.1 | 20 | ** Roles / Identity / Reputation |
| |
1.1 | 21 | * **AKEL (AI Knowledge Extraction Layer)** |
| 22 | * **Federation Layer** | ||
| 23 | * **Workers & Background Jobs** | ||
| 24 | * **Storage Layer (Postgres + VectorDB + ObjectStore)** | ||
| 25 | |||
| |
6.12 | 26 | {{include reference="Archive.FactHarbor V0\.9\.23 Lost Data.Specification.Diagrams.High-Level Architecture.WebHome"/}} |
| |
1.1 | 27 | |
| 28 | Key ideas: | ||
| 29 | |||
| |
5.1 | 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 | ||
| |
1.1 | 35 | |
| |
5.1 | 36 | ---- |
| |
1.1 | 37 | |
| |
5.1 | 38 | = Storage Architecture = |
| 39 | |||
| |
1.1 | 40 | FactHarbor separates structured data, embeddings, and evidence files: |
| 41 | |||
| |
5.1 | 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 | ||
| |
1.1 | 46 | |
| |
6.13 | 47 | {{include reference="Archive.FactHarbor V0\.9\.23 Lost Data.Specification.Diagrams.Storage Architecture.WebHome"/}} |
| |
1.1 | 48 | |
| |
5.1 | 49 | ---- |
| |
1.1 | 50 | |
| |
5.1 | 51 | = Core Backend Module Architecture = |
| 52 | |||
| |
1.1 | 53 | Each module has a clear responsibility and versioned boundaries to allow future extraction into microservices. |
| 54 | |||
| |
5.1 | 55 | == Claim Processing Module == |
| |
1.1 | 56 | |
| 57 | Responsibilities: | ||
| 58 | |||
| |
5.1 | 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 | ||
| |
1.1 | 65 | |
| |
5.1 | 66 | Flow: |
| 67 | **Ingest → Normalize → Classify → Deduplicate → Cluster** | ||
| |
1.1 | 68 | |
| |
5.1 | 69 | ---- |
| |
1.1 | 70 | |
| |
5.1 | 71 | == Scenario Engine == |
| 72 | |||
| |
1.1 | 73 | Responsibilities: |
| 74 | |||
| |
5.1 | 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 | ||
| |
1.1 | 80 | |
| |
5.1 | 81 | Flow: |
| 82 | **Create → Validate → Version → Lifecycle → Safety** | ||
| |
1.1 | 83 | |
| |
5.1 | 84 | ---- |
| |
1.1 | 85 | |
| |
5.1 | 86 | == Evidence Repository == |
| 87 | |||
| |
1.1 | 88 | Responsibilities: |
| 89 | |||
| |
5.1 | 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 | ||
| |
1.1 | 96 | |
| |
5.1 | 97 | Flow: |
| 98 | **Store → Classify → Score → Version → Update/Retract** | ||
| |
1.1 | 99 | |
| |
5.1 | 100 | ---- |
| |
1.1 | 101 | |
| |
5.1 | 102 | == Verdict Engine == |
| 103 | |||
| |
1.1 | 104 | Responsibilities: |
| 105 | |||
| |
5.1 | 106 | * Aggregate scenario-linked evidence |
| |
4.1 | 107 | * Compute likelihood ranges **per scenario** |
| |
5.1 | 108 | * Generate reasoning chain |
| 109 | * Track uncertainty factors | ||
| 110 | * Maintain verdict version timelines | ||
| |
1.1 | 111 | |
| |
5.1 | 112 | Flow: |
| 113 | **Aggregate → Compute → Explain → Version → Timeline** | ||
| |
1.1 | 114 | |
| |
5.1 | 115 | ---- |
| |
1.1 | 116 | |
| |
5.1 | 117 | == Re-evaluation Engine == |
| 118 | |||
| |
1.1 | 119 | Responsibilities: |
| 120 | |||
| |
5.1 | 121 | * Listen for upstream changes |
| 122 | * Trigger partial or full recomputation | ||
| 123 | * Update verdicts + summary views | ||
| 124 | * Maintain consistency across federated nodes | ||
| |
1.1 | 125 | |
| 126 | Triggers include: | ||
| 127 | |||
| |
5.1 | 128 | * Evidence updated or retracted |
| 129 | * Scenario definition or assumption changes | ||
| 130 | * Claim type or evaluability changes | ||
| 131 | * Contradiction detection | ||
| 132 | * Federation sync updates | ||
| |
1.1 | 133 | |
| |
5.1 | 134 | Flow: |
| 135 | **Trigger → Impact Analysis → Recompute → Publish Update** | ||
| |
1.1 | 136 | |
| |
5.1 | 137 | ---- |
| |
1.1 | 138 | |
| |
5.1 | 139 | = AKEL Integration Summary = |
| |
1.1 | 140 | |
| |
5.1 | 141 | AKEL is fully documented in its own chapter. |
| 142 | Here is only the architectural integration summary: | ||
| |
1.1 | 143 | |
| |
5.1 | 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 | |||
| |
1.1 | 152 | AKEL runs in parallel to human review — never overrides it. |
| 153 | |||
| |
6.10 | 154 | {{include reference="Archive.FactHarbor V0\.9\.23 Lost Data.Specification.Diagrams.AKEL Architecture.WebHome"/}} |
| |
1.1 | 155 | |
| |
5.1 | 156 | ---- |
| |
1.1 | 157 | |
| |
5.1 | 158 | = Federated Architecture = |
| 159 | |||
| |
1.1 | 160 | Each FactHarbor node: |
| 161 | |||
| |
5.1 | 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 | ||
| |
1.1 | 167 | |
| 168 | Nodes synchronize via: | ||
| 169 | |||
| |
5.1 | 170 | * Signed version bundles |
| 171 | * Merkle-tree lineage structures | ||
| 172 | * Optionally IPFS for evidence | ||
| 173 | * Trust-weighted acceptance | ||
| |
1.1 | 174 | |
| 175 | Benefits: | ||
| 176 | |||
| |
5.1 | 177 | * Community independence |
| 178 | * Scalability | ||
| 179 | * Resilience | ||
| 180 | * Domain specialization | ||
| |
1.1 | 181 | |
| |
6.11 | 182 | {{include reference="Archive.FactHarbor V0\.9\.23 Lost Data.Specification.Diagrams.Federation Architecture.WebHome"/}} |
| |
1.1 | 183 | |
| |
5.1 | 184 | ---- |
| |
1.1 | 185 | |
| |
5.1 | 186 | = Request → Verdict Flow = |
| 187 | |||
| |
1.1 | 188 | Simple end-to-end flow: |
| 189 | |||
| |
5.1 | 190 | **User → UI Frontend → REST API → FactHarbor Core |
| 191 | → (Claim Processing → Scenario Engine → Evidence Repository → Verdict Engine) | ||
| 192 | → Summary View → UI Frontend → User** | ||
| |
1.1 | 193 | |
| 194 | |||
| |
5.1 | 195 | ---- |
| 196 | |||
| 197 | = Federation Sync Workflow = | ||
| 198 | |||
| |
1.1 | 199 | Sequence: |
| 200 | |||
| |
5.1 | 201 | **Detect Local Change → Build Signed Bundle → Push to Peers → Validate Signature → Merge or Fork → Trigger Re-evaluation** |
| |
1.1 | 202 | |
| 203 | |||
| |
5.1 | 204 | ---- |
| 205 | |||
| 206 | = Versioning Architecture = | ||
| 207 | |||
| |
1.1 | 208 | All entities (Claim, Scenario, Evidence, Verdict) use immutable version chains: |
| 209 | |||
| |
5.1 | 210 | * VersionID |
| 211 | * ParentVersionID | ||
| 212 | * Timestamp | ||
| 213 | * AuthorType (Human, AI, ExternalNode) | ||
| 214 | * ChangeReason | ||
| 215 | * Signature (optional POC, required in 1.0) | ||
| |
1.1 | 216 | |
| |
6.14 | 217 | {{include reference="Archive.FactHarbor V0\.9\.23 Lost Data.Specification.Diagrams.Versioning Architecture.WebHome"/}} |