Changes for page Architecture

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

From 3.1 to 2.6 From 5.1 to 4.1

From version 4.1

edited by Robert Schaub
on 2025/12/12 08:32

Change comment: Imported from XAR

To version 3.1

edited by Robert Schaub
on 2025/12/11 21:35

Change comment: Imported from XAR

Raw
Rendered

Summary

Page properties (1 modified, 0 added, 0 removed)

Details

Page properties

Content

@@ -3,19 +3,21 @@
  FactHarbor uses a modular-monolith architecture (POC → Beta 0) designed to evolve into a distributed, federated, multi-node system (Release 1.0+).
  Modules are strongly separated, versioned, and auditable. All logic is transparent and deterministic.
--== High-Level System Architecture ==
++----
++= High-Level System Architecture =
++
  FactHarbor is composed of the following major modules:
  * **UI Frontend**
  * **REST API Layer**
  * **Core Logic Layer**
--** Claim Processing
--** Scenario Engine
--** Evidence Repository
--** Verdict Engine
--** Re-evaluation Engine
--** Roles / Identity / Reputation
++**– Claim Processing
++– Scenario Engine
++– Evidence Repository
++– Verdict Engine
++– Re-evaluation Engine
++– Roles / Identity / Reputation**
  * **AKEL (AI Knowledge Extraction Layer)**
  * **Federation Layer**
  * **Workers & Background Jobs**
@@ -25,170 +25,191 @@
  Key ideas:
--* Core logic is deterministic, auditable, and versioned.
--* AKEL drafts structured outputs but never publishes directly.
--* Workers run long or asynchronous tasks.
--* Storage is separated for scalability and clarity.
--* Federation Layer provides optional distributed operation.
++* Core logic is deterministic, auditable, and versioned
++* AKEL drafts structured outputs but never publishes directly
++* Workers run long or asynchronous tasks
++* Storage is separated for scalability and clarity
++* Federation Layer provides optional distributed operation
--== Storage Architecture ==
++----
++= Storage Architecture =
++
  FactHarbor separates structured data, embeddings, and evidence files:
--* **PostgreSQL** — canonical structured entities, all versioning, lineage, signatures.
--* **Vector DB (Qdrant or pgvector)** — semantic search, duplication detection, cluster mapping.
--* **Object Storage** — PDFs, datasets, raw evidence, transcripts.
--* **Optional (Release 1.0)**: Redis for caching, IPFS for decentralized object storage.
++* **PostgreSQL** — canonical structured entities, all versioning, lineage, signatures
++* **Vector DB (Qdrant or pgvector)** — semantic search, duplication detection, cluster mapping
++* **Object Storage** — PDFs, datasets, raw evidence, transcripts
++* **Optional (Release 1.0)**: Redis for caching, IPFS for decentralized object storage
  {{include reference="FactHarbor.Specification.Diagrams.Storage Architecture.WebHome"/}}
--== Core Backend Module Architecture ==
++----
++= Core Backend Module Architecture =
++
  Each module has a clear responsibility and versioned boundaries to allow future extraction into microservices.
--=== Claim Processing Module ===
++== Claim Processing Module ==
  Responsibilities:
--* Ingest text, URLs, documents, transcripts, federated input
--* Extract claims (AKEL-assisted)
--* Normalize structure
--* Classify (type, domain, evaluability, safety)
--* Deduplicate via embeddings
--* Assign to claim clusters
++* Ingest text, URLs, documents, transcripts, federated input
++* Extract claims (AKEL-assisted)
++* Normalize structure
++* Classify (type, domain, evaluability, safety)
++* Deduplicate via embeddings
++* Assign to claim clusters
--Flow: **Ingest → Normalize → Classify → Deduplicate → Cluster**
++Flow:
++**Ingest → Normalize → Classify → Deduplicate → Cluster**
--=== Scenario Engine ===
++----
++== Scenario Engine ==
++
  Responsibilities:
--* Create and validate scenarios
--* Enforce required fields (definitions, assumptions, boundaries...)
--* Perform safety checks (AKEL-assisted)
--* Manage versioning and lifecycle
--* Provide contextual evaluation settings to the Verdict Engine
++* Create and validate scenarios
++* Enforce required fields (definitions, assumptions, boundaries...)
++* Perform safety checks (AKEL-assisted)
++* Manage versioning and lifecycle
++* Provide contextual evaluation settings to the Verdict Engine
--Flow: **Create → Validate → Version → Lifecycle → Safety**
++Flow:
++**Create → Validate → Version → Lifecycle → Safety**
--=== Evidence Repository ===
++----
++== Evidence Repository ==
++
  Responsibilities:
--* Store metadata + files (object store)
--* Classify evidence
--* Compute preliminary reliability
--* Maintain version history
--* Detect retractions or disputes
--* Provide structured metadata to the Verdict Engine
++* Store metadata + files (object store)
++* Classify evidence
++* Compute preliminary reliability
++* Maintain version history
++* Detect retractions or disputes
++* Provide structured metadata to the Verdict Engine
--Flow: **Store → Classify → Score → Version → Update/Retract**
++Flow:
++**Store → Classify → Score → Version → Update/Retract**
--=== Verdict Engine ===
++----
++== Verdict Engine ==
++
  Responsibilities:
--* Aggregate scenario-linked evidence
--* Compute likelihood ranges **per scenario**
--* Generate reasoning chain
--* Track uncertainty factors
--* Maintain verdict version timelines
++* Aggregate scenario-linked evidence
++* Compute likelihood ranges
++* Generate reasoning chain
++* Track uncertainty factors
++* Maintain verdict version timelines
--Flow: **Aggregate → Compute → Explain → Version → Timeline**
++Flow:
++**Aggregate → Compute → Explain → Version → Timeline**
--=== Re-evaluation Engine ===
++----
++== Re-evaluation Engine ==
++
  Responsibilities:
--* Listen for upstream changes
--* Trigger partial or full recomputation
--* Update verdicts + summary views
--* Maintain consistency across federated nodes
++* Listen for upstream changes
++* Trigger partial or full recomputation
++* Update verdicts + summary views
++* Maintain consistency across federated nodes
  Triggers include:
--* Evidence updated or retracted
--* Scenario definition or assumption changes
--* Claim type or evaluability changes
--* Contradiction detection
--* Federation sync updates
++* Evidence updated or retracted
++* Scenario definition or assumption changes
++* Claim type or evaluability changes
++* Contradiction detection
++* Federation sync updates
--Flow: **Trigger → Impact Analysis → Recompute → Publish Update**
++Flow:
++**Trigger → Impact Analysis → Recompute → Publish Update**
--== AKEL Integration Summary ==
++----
--AKEL is fully documented in its own chapter. Here is only the architectural integration summary:
++= AKEL Integration Summary =
--* Receives raw input for claims
--* Proposes scenario drafts
--* Extracts and summarizes evidence
--* Gives reliability hints
--* Suggests draft verdicts
--* Monitors contradictions
--* Syncs metadata with trusted nodes
++AKEL is fully documented in its own chapter.
++Here is only the architectural integration summary:
++* Receives raw input for claims
++* Proposes scenario drafts
++* Extracts and summarizes evidence
++* Gives reliability hints
++* Suggests draft verdicts
++* Monitors contradictions
++* Syncs metadata with trusted nodes
++
  AKEL runs in parallel to human review — never overrides it.
  {{include reference="FactHarbor.Specification.Diagrams.AKEL Architecture.WebHome"/}}
--== Federated Architecture ==
++----
++= Federated Architecture =
++
  Each FactHarbor node:
--* Has its own dataset (claims, scenarios, evidence, verdicts)
--* Runs its own AKEL
--* Maintains local governance and reviewer rules
--* May partially mirror global or domain-specific data
--* Contributes to global knowledge clusters
++* Has its own dataset (claims, scenarios, evidence, verdicts)
++* Runs its own AKEL
++* Maintains local governance and reviewer rules
++* May partially mirror global or domain-specific data
++* Contributes to global knowledge clusters
  Nodes synchronize via:
--* Signed version bundles
--* Merkle-tree lineage structures
--* Optionally IPFS for evidence
--* Trust-weighted acceptance
++* Signed version bundles
++* Merkle-tree lineage structures
++* Optionally IPFS for evidence
++* Trust-weighted acceptance
  Benefits:
--* Community independence
--* Scalability
--* Resilience
--* Domain specialization
++* Community independence
++* Scalability
++* Resilience
++* Domain specialization
  {{include reference="FactHarbor.Specification.Diagrams.Federation Architecture.WebHome"/}}
--== Request → Verdict Flow ==
++----
++= Request → Verdict Flow =
++
  Simple end-to-end flow:
--1. User
--2. UI Frontend
--3. REST API
--4. FactHarbor Core (Processing)
--5. Summary View
--6. UI Frontend
--7. User
++**User → UI Frontend → REST API → FactHarbor Core
++      → (Claim Processing → Scenario Engine → Evidence Repository → Verdict Engine)
++      → Summary View → UI Frontend → User**
--== Federation Sync Workflow ==
++----
++
++= Federation Sync Workflow =
++
  Sequence:
--1. Detect Local Change
--2. Build Signed Bundle
--3. Push to Peers
--4. Validate Signature
--5. Merge or Fork
--6. Trigger Re-evaluation
++**Detect Local Change → Build Signed Bundle → Push to Peers → Validate Signature → Merge or Fork → Trigger Re-evaluation**
--== Versioning Architecture ==
++----
++
++= Versioning Architecture =
++
  All entities (Claim, Scenario, Evidence, Verdict) use immutable version chains:
--* VersionID
--* ParentVersionID
--* Timestamp
--* AuthorType (Human, AI, ExternalNode)
--* ChangeReason
--* Signature (optional POC, required in 1.0)
++* VersionID
++* ParentVersionID
++* Timestamp
++* AuthorType (Human, AI, ExternalNode)
++* ChangeReason
++* Signature (optional POC, required in 1.0)
  {{include reference="FactHarbor.Specification.Diagrams.Versioning Architecture.WebHome"/}}

Changes for page Architecture

Summary

Details

Applications

Navigation

Need help?