Wiki source code of Architecture
Version 3.1 by Robert Schaub on 2025/12/11 21:35
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 | |||
| 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 | |||
| |
3.1 | 26 | {{include reference="FactHarbor.Specification.Diagrams.High-Level Architecture.WebHome"/}} |
| |
1.1 | 27 | |
| 28 | Key ideas: | ||
| 29 | |||
| |
2.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 | |
| 36 | ---- | ||
| 37 | |||
| 38 | = Storage Architecture = | ||
| 39 | |||
| 40 | FactHarbor separates structured data, embeddings, and evidence files: | ||
| 41 | |||
| |
2.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 | |
| |
3.1 | 47 | {{include reference="FactHarbor.Specification.Diagrams.Storage Architecture.WebHome"/}} |
| |
1.1 | 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 | |||
| |
2.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 | |
| 66 | Flow: | ||
| 67 | **Ingest → Normalize → Classify → Deduplicate → Cluster** | ||
| 68 | |||
| 69 | ---- | ||
| 70 | |||
| 71 | == Scenario Engine == | ||
| 72 | |||
| 73 | Responsibilities: | ||
| 74 | |||
| |
2.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 | |
| 81 | Flow: | ||
| 82 | **Create → Validate → Version → Lifecycle → Safety** | ||
| 83 | |||
| 84 | ---- | ||
| 85 | |||
| 86 | == Evidence Repository == | ||
| 87 | |||
| 88 | Responsibilities: | ||
| 89 | |||
| |
2.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 | |
| 97 | Flow: | ||
| 98 | **Store → Classify → Score → Version → Update/Retract** | ||
| 99 | |||
| 100 | ---- | ||
| 101 | |||
| 102 | == Verdict Engine == | ||
| 103 | |||
| 104 | Responsibilities: | ||
| 105 | |||
| |
2.1 | 106 | * Aggregate scenario-linked evidence |
| 107 | * Compute likelihood ranges | ||
| 108 | * Generate reasoning chain | ||
| 109 | * Track uncertainty factors | ||
| 110 | * Maintain verdict version timelines | ||
| |
1.1 | 111 | |
| 112 | Flow: | ||
| 113 | **Aggregate → Compute → Explain → Version → Timeline** | ||
| 114 | |||
| 115 | ---- | ||
| 116 | |||
| 117 | == Re-evaluation Engine == | ||
| 118 | |||
| 119 | Responsibilities: | ||
| 120 | |||
| |
2.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 | |||
| |
2.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 | |
| 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 | |||
| |
2.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 | ||
| |
1.1 | 151 | |
| 152 | AKEL runs in parallel to human review — never overrides it. | ||
| 153 | |||
| |
3.1 | 154 | {{include reference="FactHarbor.Specification.Diagrams.AKEL Architecture.WebHome"/}} |
| |
1.1 | 155 | |
| 156 | ---- | ||
| 157 | |||
| 158 | = Federated Architecture = | ||
| 159 | |||
| 160 | Each FactHarbor node: | ||
| 161 | |||
| |
2.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 | |||
| |
2.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 | |||
| |
2.1 | 177 | * Community independence |
| 178 | * Scalability | ||
| 179 | * Resilience | ||
| 180 | * Domain specialization | ||
| |
1.1 | 181 | |
| |
3.1 | 182 | {{include reference="FactHarbor.Specification.Diagrams.Federation Architecture.WebHome"/}} |
| |
1.1 | 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 | |||
| |
2.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 | |
| |
3.1 | 217 | {{include reference="FactHarbor.Specification.Diagrams.Versioning Architecture.WebHome"/}} |