Wiki source code of Architecture

Last modified by Robert Schaub on 2025/12/24 20:34

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"/}}