Requirements

This chapter defines all functional, non-functional, user-role, and federation requirements for FactHarbor.

It answers:

• Who can do what in the system?  
• What workflows must FactHarbor support?  
• What quality, transparency, and federation guarantees must be met?  

User Roles

Reader

Responsibilities:

• Browse and search claims  
• View scenarios, evidence, verdicts, and timelines  
• Compare scenarios and explore assumptions  
• Flag issues, errors, contradictions, or suspicious patterns  

Permissions:

• Read-only access to all published claims, scenarios, evidence, and verdicts  
• Use filters, search, and visualization tools (“truth landscape”, timelines, scenario comparison, etc.)  
• Create personal views (saved searches, bookmarks, etc.)  

Limitations:

• Cannot change shared content  
• Cannot publish new claims, scenarios, or verdicts  

Contributor

Responsibilities:

• Submit claims  
• Propose new claim clusters (if automatic clustering is insufficient)  
• Draft scenarios (definitions, assumptions, boundaries)  
• Attach evidence (sources, documents, links, datasets)  
• Suggest verdict drafts and uncertainty ranges  
• Respond to reviewer or expert feedback  

Permissions:

• Everything a Reader can do  
• Create and edit draft claims, scenarios, evidence links, and verdict drafts  
• Comment on existing content and discuss assumptions  
• Propose corrections to misclassified or outdated content  

Limitations:

• Cannot *publish* or mark content as “reviewed” or “approved”  
• Cannot override expert or maintainer decisions  
• Cannot change system-level settings, roles, or federation configuration  

Reviewer

Responsibilities:

• Review contributions from Contributors and AKEL drafts  
• Check internal consistency and clarity of scenarios  
• Validate that evidence is correctly linked and described  
• Ensure verdicts match the evidence and stated assumptions  
• Reject, request change, or accept content  

Permissions:

• Everything a Contributor can do  
• Change content status from `draft` → `in review` → `published` / `rejected`  
• Send content back to Contributors with comments  
• Flag content for expert review  

Limitations:

• Cannot modify system-wide configuration or federation topology  
• Cannot unilaterally change expert conclusions without process  

Expert

Responsibilities:

• Provide domain-specific judgment on scenarios, evidence, and verdicts  
• Refine assumptions and definitions in complex or ambiguous topics  
• Identify subtle biases, missing evidence, or misinterpretations  
• Propose improved verdicts and uncertainty assessments  

Permissions:

• Everything a Reviewer can do  
• Attach expert annotations and signed opinions to scenarios and verdicts  
• Propose re-evaluation of already published content based on new evidence  

Limitations:

• Expert status is scoped to specific domains  
• Cannot bypass moderation, abuse policies, or legal constraints  

Moderator

Responsibilities:

• Handle abuse reports, spam, harassment, and coordinated manipulation  
• Enforce community guidelines and legal constraints  
• Manage user bans, content takedowns, and visibility restrictions  

Permissions:

• Hide or temporarily disable access to abusive content  
• Ban or restrict users in line with policy  
• Edit or redact sensitive content (e.g., doxxing, illegal material)  

Limitations:

• Does not change factual verdicts except where required for legal / safety reasons  
• Substantive fact changes must go through the review / expert process  

Maintainer / Administrator

Responsibilities:

• Maintain node configuration, security settings, and backups  
• Configure AKEL, storage, federation endpoints, and performance tuning  
• Manage role assignments (who is Reviewer, Expert, Moderator, etc.)  
• Approve software updates and schema migrations  

Permissions:

• All read/write access to configuration, but not necessarily content editorial authority  
• Define organization-level policies (e.g., which sources are allowed by default)  

Limitations:

• Editorial decisions on controversial topics follow governance rules, not arbitrary admin choice  

AKEL (AI Knowledge Extraction Layer)

Responsibilities:

• Propose drafts — never final decisions  
• Normalize claims and extract candidate clusters  
• Draft scenarios, evidence candidates, and preliminary verdict suggestions  
• Propose re-evaluation when new evidence appears  

Permissions:

• Create and update machine-generated drafts and suggestions  
• Never directly publish content without human approval  

Limitations:

• AKEL output is always labeled as AI-generated draft  
• Must be reviewable, auditable, and overridable by humans  

Functional Requirements

This section defines what the system must do.

Claim Intake & Normalization

FR1 – Claim Intake

The system must support Claim creation from:

• Free-text input  
• URLs (web pages, articles, posts)  
• Uploaded documents and transcripts  
• Structured feeds (optional, e.g. from partner platforms)  

Accepted sources:

• Text entered by users  
• URLs  
• Uploaded documents  
• Transcripts  
• Automated ingestion (optional federation input)  
• AKEL extraction from multi-claim texts  

FR2 – Claim Normalization

• Convert diverse inputs into short, structured, declarative claims  
• Preserve original phrasing for reference  
• Avoid hidden reinterpretation; differences between original and normalized phrasing must be visible  

FR3 – Claim Classification

• Classify claims by topic, domain, and type (e.g., quantitative, causal, normative)  
• Suggest which node / experts are relevant  

FR4 – Claim Clustering

• Group similar claims into Claim Clusters  
• Allow manual correction of cluster membership  
• Provide explanation why two claims are considered “same cluster”  

Scenario System

FR5 – Scenario Creation

• Contributors, Reviewers, and Experts can create scenarios  
• AKEL can propose draft scenarios  
• Each scenario is tied to exactly one Claim Cluster  

FR6 – Required Scenario Fields

Each scenario includes:

• Definitions (key terms)  
• Assumptions (explicit, testable where possible)  
• Boundaries (time, geography, population, conditions)  
• Scope of evidence considered  
• Intended decision / context (optional)  

FR7 – Scenario Versioning

• Every change to a scenario creates a new version  
• Previous versions remain accessible with timestamps and rationale  

FR8 – Scenario Comparison

• Users can compare scenarios side by side  
• Show differences in assumptions, definitions, and evidence sets  

Evidence Management

FR9 – Evidence Ingestion

• Attach external sources (articles, studies, datasets, reports, transcripts) to Scenarios  
• Allow multiple pieces of evidence per Scenario  

FR10 – Evidence Assessment

For each piece of evidence:

• Assign reliability / quality ratings  
• Capture who rated it and why  
• Indicate known limitations, biases, or conflicts of interest  

FR11 – Evidence Linking

• Link one piece of evidence to multiple scenarios if relevant  
• Make dependencies explicit (e.g., “Scenario A uses subset of evidence used in Scenario B”)  

Verdicts & Truth Landscape

FR12 – Scenario Verdicts

For each Scenario:

• Provide a probability- or likelihood-based verdict  
• Capture uncertainty and reasoning  
• Distinguish between AKEL draft and human-approved verdict  

FR13 – Truth Landscape

• Aggregate all scenario-specific verdicts into a “truth landscape” for a claim  
• Make disagreements visible rather than collapsing them into a single binary result  

FR14 – Time Evolution

• Show how verdicts and evidence evolve over time  
• Allow users to see “as of date X, what did we know?”  

Workflow, Moderation & Audit

FR15 – Workflow States

• Draft → In Review → Published / Rejected  
• Separate states for Claims, Scenarios, Evidence, and Verdicts  

FR16 – Moderation & Abuse Handling

• Allow Moderators to hide content or lock edits for abuse or legal reasons  
• Keep internal audit trail even if public view is restricted  

FR17 – Audit Trail

• Every significant action (create, edit, publish, delete/hide) is logged with:  
• Who did it  
• When  
• What changed  
• Why (short comment, optional but recommended)  

Federation Requirements

FactHarbor is designed to operate as a federated network of nodes.

FR18 – Node Autonomy

• Each node can run independently (local policies, local users, local moderation)  
• Nodes decide which other nodes to federate with  

FR19 – Data Sharing Modes

Nodes must be able to:

• Share claims and summaries only  
• Share selected claims, scenarios, and verdicts  
• Share full underlying evidence metadata where allowed  
• Opt-out of sharing sensitive or restricted content  

FR20 – Synchronization & Conflict Handling

• Changes from remote nodes must be mergeable or explicitly conflict-marked  
• Conflicting verdicts are allowed and visible; not forced into consensus  

FR21 – Federation Discovery

• Discover other nodes and their capabilities (public endpoints, policies)  
• Allow whitelisting / blacklisting of nodes  

Basic federation (minimum):

• Subscribe to and import selected claims and scenarios from other nodes  
• Keep provenance (which node originated what)  
• Respect remote deletion / redaction notices where required by policy or law  

Advanced federation (later versions):

• Cross-node search  
• Federation-wide discovery and reputation signals  

Non-Functional Requirements (NFR)

NFR1 – Transparency

• All assumptions, evidence, and reasoning behind verdicts must be visible  
• AKEL involvement must be clearly labeled  
• Users must be able to inspect the chain of reasoning and versions  

NFR2 – Security

• Role-based access control  
• Transport-level security (HTTPS)  
• Secure storage of secrets (API keys, credentials)  
• Audit trails for sensitive actions  

NFR3 – Privacy & Compliance

• Configurable data retention policies  
• Ability to redact or pseudonymize personal data when required  
• Compliance hooks for jurisdiction-specific rules (e.g. GDPR-like deletion requests)  

NFR4 – Performance

• POC: typical interactions < 2 s  
• Release 1.0: < 300 ms for common read operations after caching  
• Degradation strategies under load (e.g. partial federation results, limited history)  

NFR5 – Scalability

• POC: 50 internal testers on one node  
• Beta 0: 100 external testers on one node  
• Release 1.0: 2000+ concurrent users on a reasonably provisioned node  

Suggested technical targets for Release 1.0:

• Scalable monolith or early microservice architecture  
• Sharded vector database (for semantic search)  
• Optional IPFS or other decentralized storage for large artefacts  
• Horizontal scalability for read capacity  

NFR6 – Interoperability

• Open, documented API  
• Modular AKEL that can be swapped or extended  
• Federation protocols that follow open standards where possible  
• Standard model for external integrations (e.g. news platforms, research tools)  

NFR7 – Observability & Operations

• Metrics for performance, errors, and queue backlogs  
• Logs for key flows (claim intake, scenario changes, verdict updates, federation sync)  
• Health endpoints for monitoring  

NFR8 – Maintainability

• Clear module boundaries (API, core services, AKEL, storage, federation)  
• Backward-compatible schema migration strategy where feasible  
• Configuration via files / environment variables, not hard-coded  

NFR9 – Usability

• UI optimized for exploring complexity, not hiding it  
• Support for saved views, filters, and user-level preferences  
• Progressive disclosure: casual users see summaries, advanced users can dive deep  

Release Levels

Proof of Concept (POC)

• Single node  
• Limited user set (50 internal testers)  
• Basic claim → scenario → evidence → verdict flow  
• Minimal federation (optional)  

Beta 0

• One or few nodes  
• External testers (100)  
• Expanded workflows and basic moderation  
• Initial federation experiments  

Release 1.0

• 2000+ concurrent users  
• Scalable monolith or early microservices  
• Sharded vector DB  
• IPFS optional  
• High automation (AKEL assistance)  
• Multi-node federation