Wiki source code of Architecture
Version 4.1 by Robert Schaub on 2025/12/12 08:32
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 | |||
| |
4.1 | 6 | == High-Level System Architecture == |
| |
1.1 | 7 | |
| 8 | FactHarbor is composed of the following major modules: | ||
| 9 | |||
| 10 | * **UI Frontend** | ||
| 11 | * **REST API Layer** | ||
| 12 | * **Core Logic Layer** | ||
| |
4.1 | 13 | ** Claim Processing |
| 14 | ** Scenario Engine | ||
| 15 | ** Evidence Repository | ||
| 16 | ** Verdict Engine | ||
| 17 | ** Re-evaluation Engine | ||
| 18 | ** Roles / Identity / Reputation | ||
| |
1.1 | 19 | * **AKEL (AI Knowledge Extraction Layer)** |
| 20 | * **Federation Layer** | ||
| 21 | * **Workers & Background Jobs** | ||
| 22 | * **Storage Layer (Postgres + VectorDB + ObjectStore)** | ||
| 23 | |||
| |
3.1 | 24 | {{include reference="FactHarbor.Specification.Diagrams.High-Level Architecture.WebHome"/}} |
| |
1.1 | 25 | |
| 26 | Key ideas: | ||
| 27 | |||
| |
4.1 | 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. | ||
| |
1.1 | 33 | |
| |
4.1 | 34 | == Storage Architecture == |
| |
1.1 | 35 | |
| 36 | FactHarbor separates structured data, embeddings, and evidence files: | ||
| 37 | |||
| |
4.1 | 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. | ||
| |
1.1 | 42 | |
| |
3.1 | 43 | {{include reference="FactHarbor.Specification.Diagrams.Storage Architecture.WebHome"/}} |
| |
1.1 | 44 | |
| |
4.1 | 45 | == Core Backend Module Architecture == |
| |
1.1 | 46 | |
| 47 | Each module has a clear responsibility and versioned boundaries to allow future extraction into microservices. | ||
| 48 | |||
| |
4.1 | 49 | === Claim Processing Module === |
| |
1.1 | 50 | |
| 51 | Responsibilities: | ||
| 52 | |||
| |
4.1 | 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 | ||
| |
1.1 | 59 | |
| |
4.1 | 60 | Flow: **Ingest → Normalize → Classify → Deduplicate → Cluster** |
| |
1.1 | 61 | |
| |
4.1 | 62 | === Scenario Engine === |
| |
1.1 | 63 | |
| 64 | Responsibilities: | ||
| 65 | |||
| |
4.1 | 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 | ||
| |
1.1 | 71 | |
| |
4.1 | 72 | Flow: **Create → Validate → Version → Lifecycle → Safety** |
| |
1.1 | 73 | |
| |
4.1 | 74 | === Evidence Repository === |
| |
1.1 | 75 | |
| 76 | Responsibilities: | ||
| 77 | |||
| |
4.1 | 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 | ||
| |
1.1 | 84 | |
| |
4.1 | 85 | Flow: **Store → Classify → Score → Version → Update/Retract** |
| |
1.1 | 86 | |
| |
4.1 | 87 | === Verdict Engine === |
| |
1.1 | 88 | |
| 89 | Responsibilities: | ||
| 90 | |||
| |
4.1 | 91 | * Aggregate scenario-linked evidence |
| 92 | * Compute likelihood ranges **per scenario** | ||
| 93 | * Generate reasoning chain | ||
| 94 | * Track uncertainty factors | ||
| 95 | * Maintain verdict version timelines | ||
| |
1.1 | 96 | |
| |
4.1 | 97 | Flow: **Aggregate → Compute → Explain → Version → Timeline** |
| |
1.1 | 98 | |
| |
4.1 | 99 | === Re-evaluation Engine === |
| |
1.1 | 100 | |
| 101 | Responsibilities: | ||
| 102 | |||
| |
4.1 | 103 | * Listen for upstream changes |
| 104 | * Trigger partial or full recomputation | ||
| 105 | * Update verdicts + summary views | ||
| 106 | * Maintain consistency across federated nodes | ||
| |
1.1 | 107 | |
| 108 | Triggers include: | ||
| 109 | |||
| |
4.1 | 110 | * Evidence updated or retracted |
| 111 | * Scenario definition or assumption changes | ||
| 112 | * Claim type or evaluability changes | ||
| 113 | * Contradiction detection | ||
| 114 | * Federation sync updates | ||
| |
1.1 | 115 | |
| |
4.1 | 116 | Flow: **Trigger → Impact Analysis → Recompute → Publish Update** |
| |
1.1 | 117 | |
| |
4.1 | 118 | == AKEL Integration Summary == |
| |
1.1 | 119 | |
| |
4.1 | 120 | AKEL is fully documented in its own chapter. Here is only the architectural integration summary: |
| |
1.1 | 121 | |
| |
4.1 | 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 | ||
| |
1.1 | 129 | |
| 130 | AKEL runs in parallel to human review — never overrides it. | ||
| 131 | |||
| |
3.1 | 132 | {{include reference="FactHarbor.Specification.Diagrams.AKEL Architecture.WebHome"/}} |
| |
1.1 | 133 | |
| |
4.1 | 134 | == Federated Architecture == |
| |
1.1 | 135 | |
| 136 | Each FactHarbor node: | ||
| 137 | |||
| |
4.1 | 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 | ||
| |
1.1 | 143 | |
| 144 | Nodes synchronize via: | ||
| 145 | |||
| |
4.1 | 146 | * Signed version bundles |
| 147 | * Merkle-tree lineage structures | ||
| 148 | * Optionally IPFS for evidence | ||
| 149 | * Trust-weighted acceptance | ||
| |
1.1 | 150 | |
| 151 | Benefits: | ||
| 152 | |||
| |
4.1 | 153 | * Community independence |
| 154 | * Scalability | ||
| 155 | * Resilience | ||
| 156 | * Domain specialization | ||
| |
1.1 | 157 | |
| |
3.1 | 158 | {{include reference="FactHarbor.Specification.Diagrams.Federation Architecture.WebHome"/}} |
| |
1.1 | 159 | |
| |
4.1 | 160 | == Request → Verdict Flow == |
| |
1.1 | 161 | |
| 162 | Simple end-to-end flow: | ||
| 163 | |||
| |
4.1 | 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 | ||
| |
1.1 | 171 | |
| |
4.1 | 172 | == Federation Sync Workflow == |
| |
1.1 | 173 | |
| 174 | Sequence: | ||
| 175 | |||
| |
4.1 | 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 | ||
| |
1.1 | 182 | |
| |
4.1 | 183 | == Versioning Architecture == |
| |
1.1 | 184 | |
| 185 | All entities (Claim, Scenario, Evidence, Verdict) use immutable version chains: | ||
| 186 | |||
| |
4.1 | 187 | * VersionID |
| 188 | * ParentVersionID | ||
| 189 | * Timestamp | ||
| 190 | * AuthorType (Human, AI, ExternalNode) | ||
| 191 | * ChangeReason | ||
| 192 | * Signature (optional POC, required in 1.0) | ||
| |
1.1 | 193 | |
| |
3.1 | 194 | {{include reference="FactHarbor.Specification.Diagrams.Versioning Architecture.WebHome"/}} |