Wiki source code of Architecture

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

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	= High-Level System Architecture =
	8
	9	FactHarbor is composed of the following major modules:
	10
	11	* UI Frontend
	12	* REST API Layer
	13	* Core Logic Layer
2.1	14	** Claim Processing
	15	** Scenario Engine
	16	** Evidence Repository
	17	** Verdict Engine
	18	** Re-evaluation Engine
1.1	19	** Roles / Identity / Reputation
	20	* AKEL (AI Knowledge Extraction Layer)
	21	* Federation Layer
	22	* Workers & Background Jobs
	23	* Storage Layer (Postgres + VectorDB + ObjectStore)
	24
	25	{{include reference="FactHarbor.Specification.Diagrams.High-Level Architecture.WebHome"/}}
	26
	27	Key ideas:
	28
	29	* Core logic is deterministic, auditable, and versioned
	30	* AKEL drafts structured outputs but never publishes directly
	31	* Workers run long or asynchronous tasks
	32	* Storage is separated for scalability and clarity
	33	* Federation Layer provides optional distributed operation
	34
	35
	36	= Storage Architecture =
	37
	38	FactHarbor separates structured data, embeddings, and evidence files:
	39
	40	* PostgreSQL — canonical structured entities, all versioning, lineage, signatures
	41	* Vector DB (Qdrant or pgvector) — semantic search, duplication detection, cluster mapping
	42	* Object Storage — PDFs, datasets, raw evidence, transcripts
	43	* Optional (Release 1.0): Redis for caching, IPFS for decentralized object storage
	44
	45	{{include reference="FactHarbor.Specification.Diagrams.Storage Architecture.WebHome"/}}
	46
	47
	48	= Core Backend Module Architecture =
	49
	50	Each module has a clear responsibility and versioned boundaries to allow future extraction into microservices.
	51
	52	== 1. Claim Processing Module ==
	53
	54	Responsibilities:
	55
	56	* Ingest text, URLs, documents, transcripts, federated input
	57	* Extract claims (AKEL-assisted)
	58	* Normalize structure
	59	* Classify (type, domain, evaluability, safety)
	60	* Deduplicate via embeddings
	61	* Assign to claim clusters
	62
2.1	63	Flow:
1.1	64	Ingest → Normalize → Classify → Deduplicate → Cluster
	65
	66
	67	== 2. Scenario Engine ==
	68
	69	Responsibilities:
	70
	71	* Create and validate scenarios
	72	* Enforce required fields (definitions, assumptions, boundaries...)
	73	* Perform safety checks (AKEL-assisted)
	74	* Manage versioning and lifecycle
	75	* Provide contextual evaluation settings to the Verdict Engine
	76
2.1	77	Flow:
1.1	78	Create → Validate → Version → Lifecycle → Safety
	79
	80
	81	== 3. Evidence Repository ==
	82
	83	Responsibilities:
	84
	85	* Store metadata + files (object store)
	86	* Classify evidence
	87	* Compute preliminary reliability
	88	* Maintain version history
	89	* Detect retractions or disputes
	90	* Provide structured metadata to the Verdict Engine
	91
2.1	92	Flow:
1.1	93	Store → Classify → Score → Version → Update/Retract
	94
	95
	96	== 4. Verdict Engine ==
	97
	98	Responsibilities:
	99
	100	* Aggregate scenario-linked evidence
	101	* Compute likelihood ranges per scenario
	102	* Generate reasoning chain
	103	* Track uncertainty factors
	104	* Maintain verdict version timelines
	105
2.1	106	Flow:
1.1	107	Aggregate → Compute → Explain → Version → Timeline
	108
	109
	110	== 5. Re-evaluation Engine ==
	111
	112	Responsibilities:
	113
	114	* Listen for upstream changes
	115	* Trigger partial or full recomputation
	116	* Update verdicts + summary views
	117	* Maintain consistency across federated nodes
	118
	119	Triggers include:
	120
	121	* Evidence updated or retracted
	122	* Scenario definition or assumption changes
	123	* Claim type or evaluability changes
	124	* Contradiction detection
	125	* Federation sync updates
	126
2.1	127	Flow:
1.1	128	Trigger → Impact Analysis → Recompute → Publish Update
	129
	130
	131	= AKEL Integration Summary =
	132
	133	AKEL is fully documented in its own chapter.
	134	Here is only the architectural integration summary:
	135
	136	* Receives raw input for claims
	137	* Proposes scenario drafts
	138	* Extracts and summarizes evidence
	139	* Gives reliability hints
	140	* Suggests draft verdicts
	141	* Monitors contradictions
	142	* Syncs metadata with trusted nodes
	143
	144	AKEL runs in parallel to human review — never overrides it.
	145
	146	{{include reference="FactHarbor.Specification.Diagrams.AKEL Architecture.WebHome"/}}
	147
	148
	149	= Federated Architecture =
	150
	151	Each FactHarbor node:
	152
	153	* Has its own dataset (claims, scenarios, evidence, verdicts)
	154	* Runs its own AKEL
	155	* Maintains local governance and reviewer rules
	156	* May partially mirror global or domain-specific data
	157	* Contributes to global knowledge clusters
	158
	159	Nodes synchronize via:
	160
	161	* Signed version bundles
	162	* Merkle-tree lineage structures
	163	* Optionally IPFS for evidence
	164	* Trust-weighted acceptance
	165
	166	Benefits:
	167
	168	* Community independence
	169	* Scalability
	170	* Resilience
	171	* Domain specialization
	172
	173	{{include reference="FactHarbor.Specification.Diagrams.Federation Architecture.WebHome"/}}
	174
	175
	176	= Request → Verdict Flow =
	177
	178	Simple end-to-end flow:
	179
	180	**User → UI Frontend → REST API → FactHarbor Core
2.1	181	→ (Claim Processing → Scenario Engine → Evidence Repository → Verdict Engine)
	182	→ Summary View → UI Frontend → User**
1.1	183
	184
	185	= Federation Sync Workflow =
	186
	187	Sequence:
	188
	189	Detect Local Change → Build Signed Bundle → Push to Peers → Validate Signature → Merge or Fork → Trigger Re-evaluation
	190
	191
	192	= Versioning Architecture =
	193
	194	All entities (Claim, Scenario, Evidence, Verdict) use immutable version chains:
	195
	196	* VersionID
	197	* ParentVersionID
	198	* Timestamp
	199	* AuthorType (Human, AI, ExternalNode)
	200	* ChangeReason
	201	* Signature (optional POC, required in 1.0)
	202
	203	{{include reference="FactHarbor.Specification.Diagrams.Versioning Architecture.WebHome"/}}