Skip to content

Planned architecture

FactHarborDSS is in planning. The diagrams show the selected design, not an implemented or validated system.

Planned architecture: TypeScript browser, modular .NET application and worker, PostgreSQL evidence store, separate Source Reliability service, and checked external calls

Open the diagram for a larger view. Components show responsibilities, not security isolation. Technical users would call the same application API; the diagram shows the browser path only. Original diagram; repository-wide licensing remains undecided.

Core design

  • One application: a TypeScript interface served by C#/.NET 10, with a worker initially running in the same process.
  • Traceable evidence: PostgreSQL stores captured web content, source versions, assessments, reports and durable jobs. Full-text search provides the retrieval baseline.
  • Repeatable evidence basis: reassessment uses the saved version without hidden fetching. Refreshes create new versions; model outputs may still differ.
  • Separate source evaluation: Source Reliability has its own service interface and database. Its role in Stage 1 remains undecided.
  • Permissions enforced in code: access, report release and external actions are checked separately. Retrieved documents and AI assessments cannot grant authority; source restrictions also apply to derived reports.

Stage 1 focuses on claim checking with public web sources and saved evidence. From Stage 1 on, technical users such as AI agents acting for a responsible person would get the same functions as people through the same API as the browser interface; confirmations, permissions and approvals stay with people. Broader decision workflows and controlled external actions come later. The pipeline explains the broader assessment and agent-debate design.

Core data model

Like the FactHarbor Alpha, DSS splits a claim into atomic claims, statements that can each be assessed on their own, and gives each one its own assessment. The overall assessment builds on these. Assessments cite evidence items that quote exact passages in captured documents, and evidence with a compatible scope can be grouped into claim assessment boundaries. Every judgment records how it was established, and the report names gaps as limitations. The principles set out the rules these records serve.

erDiagram
  Claim ||--|{ AtomicClaim : "split into"
  Claim ||--o{ OverallAssessment : "assessed in"
  OverallAssessment ||--|{ AtomicClaimAssessment : "built on"
  AtomicClaim ||--o{ AtomicClaimAssessment : "assessed in"
  AtomicClaim |o--o{ SearchQuery : "searched with"
  SearchQuery }o--o{ Document : finds
  AtomicClaimAssessment ||--o{ Citation : cites
  Citation }o--|| EvidenceItem : "refers to"
  AtomicClaimAssessment ||--o{ BoundaryFinding : "finds per boundary"
  BoundaryFinding }o--|| ClaimAssessmentBoundary : for
  ClaimAssessmentBoundary }o--o{ EvidenceItem : groups
  EvidenceItem }o--|| Document : "extracted from"
  Document }o--o{ Document : "derived from"
  Document }o--|{ Source : "published by"
  Source ||--o{ ReliabilityEvaluation : "rated in"
  EvidenceItem }o--o| ReliabilityEvaluation : "weighed using"
  ReportEdition }o--o{ OverallAssessment : presents
  ReportEdition }o--o{ Limitation : names
  AtomicClaimAssessment |o--o{ Limitation : "limited by"
  OverallAssessment |o--o{ Limitation : "limited by"
  Claim {
    text wording "exact, as submitted"
    text context "speaker, date, venue"
  }
  AtomicClaim["Atomic claim"] {
    text statement
    label role "supports, contradicts or context"
    text expected_evidence
    label harm_potential "for scrutiny, never weight"
    text necessary_assignments "subject, matter, time, relation"
  }
  AtomicClaimAssessment["Atomic claim assessment"] {
    int verdict "0 false to 100 true, if reached"
    label verdict_label "seven labels, unverified or not assessed"
    label confidence
    text reasoning
    text overturn_conditions
    label established_by
  }
  OverallAssessment["Overall assessment"] {
    text reading "other readings named"
    int verdict "0 false to 100 true, if reached"
    label verdict_label "seven labels, unverified or not synthesized, with reason"
    label confidence
    text reasoning
    text decisive_atomic_claims "per direction"
    label established_by
  }
  SearchQuery["Search query"] {
    text query
    label purpose "supporting, contradicting, origin or follow-up"
  }
  Citation {
    label direction "supports, contradicts or qualifies"
    label assignment "for decisive atomic claims"
    label established_by
  }
  BoundaryFinding["Boundary finding"] {
    label direction "supports, contradicts or mixed"
    text reasoning
    label established_by
  }
  ClaimAssessmentBoundary["Claim assessment boundary"] {
    text scope "compatible method, period, region"
  }
  EvidenceItem["Evidence item"] {
    text statement_and_quote
    label substantiation "founded, partly, unfounded or not assessable"
    label origin_status
    text scope "method, period, region"
    label weight_level "very strong to very weak"
    label established_by
  }
  Document["Captured document"] {
    time captured_at
    label authenticity "for decisive evidence"
  }
  Source {
    text publisher_or_author
  }
  ReliabilityEvaluation["Reliability evaluation"] {
    label rating "seven labels or insufficient data"
    text cited_material
    date evaluated_on
  }
  ReportEdition["Report edition"] {
    time issued_at
    text supersedes "earlier edition and what changed, if corrected"
  }
  Limitation {
    label type
    text reason
  }

Simplified conceptual model of the planned design for claim assessment, not a database schema; records for decisions and actions are not shown. Read each line as a sentence, for example "a claim is split into one or more atomic claims". At a line end, a bar means one, a crow's foot many and a circle zero.

Planning documents

How it would work, the principles and the analysis pipeline complement this architecture overview. We supply detailed requirements and acceptance criteria with each agreed piece of work.