= Binary-Origami Figurator
image:https://img.shields.io/badge/License-PMPL--1.0-blue.svg[License: PMPL-1.0,link="https://github.com/hyperpolymath/palimpsest-license"]
// SPDX-License-Identifier: PMPL-1.0-or-later
// SPDX-FileCopyrightText: 2025 hyperpolymath

Infrastructure for pragmatic epistemology. Combining

• i-docs navigation,
• PROMPT epistemological scoring, and
• boundary objects theory.

An evidence graph for investigative journalism.

Status: Phase 1 (PoC) - v1.0.0 Release
Version: 1.0.0

== New Here? Start with the Wiki

[TIP]

Confused by the terminology? The link:wiki/index.adoc[Binary-Origami Wiki] explains everything in metaphors, diagrams, and plain language.

[quote]

This isn't just a database. It's infrastructure for folding and unfolding evidence—so everyone can see the shape that fits their needs.

=== Why "Binary-Origami"?

• Binary: Evidence is stored as clear, connected data (supports/contradicts, 0-100 scores)
• Origami: The same evidence can be "folded" into different forms for different audiences
• Figuration: The rules for folding/unfolding are transparent and reversible

[cols="1,2,1"]
|===
| Concept | Description | Learn More

| i-docs Navigation
| "Choose Your Own Adventure" for evidence
| link:wiki/navigation.adoc[Wiki]

| PROMPT Scoring
| "Nutrition labels" for trustworthiness
| link:wiki/prompt.adoc[Wiki]

| Boundary Objects
| "Shared maps" with multiple routes
| link:wiki/boundary-objects.adoc[Wiki]

| Evidence Graphs
| The "skeleton" beneath the origami
| link:wiki/graphs.adoc[Wiki]
|===

=== For the Impatient

1. Try the <<quick-start,Quick Start>> to see it in action
2. Skim the link:wiki/binary-origami.adoc[Binary-Origami Metaphor] page
3. Dive into the link:wiki/faqs.adoc[FAQ] if something's unclear

== Vision

We didn't fall from Truth to Post-Truth; we evolved to complex epistemology without building infrastructure. This system IS that infrastructure.

=== Core Concepts

1. i-docs Navigation: Navigation over narration, reader agency
2. PROMPT Framework: 6-dimensional epistemological scoring (Provenance, Replicability, Objective, Methodology, Publication, Transparency)
3. Boundary Objects: Multiple audience perspectives on same evidence
4. Evidence Graph for Investigative Journalism amd Related Disciplines

[[quick-start]]
== Quick Start

=== Prerequisites

• Elixir 1.18+ & Erlang/OTP 27+
• Phoenix 1.8+
• Podman & podman-compose
• just (task runner): https://github.com/casey/just

=== 1. Clone Repository

git clone https://github.com/Hyperpolymath/bofig.git
cd bofig

=== 2. Start Databases

podman-compose up -d

Verify ArangoDB is running: http://localhost:8529 (root/dev)

=== 3. Full Setup (deps, databases, seeds)

just setup

Or manually:

mix deps.get
mix ecto.create
mix run -e "EvidenceGraph.ArangoDB.setup_database()"
mix run priv/repo/seeds.exs

=== 4. Start Phoenix Server

just dev

Visit:

• Application: http://localhost:4000 (register/login required)
• GraphQL Playground: http://localhost:4000/api/graphiql (dev only)
• Health Check: http://localhost:4000/api/health

== GraphQL API Examples

=== Query: Get All Claims

query {
  claims(investigationId: "uk_inflation_2023") {
    id
    text
    claimType
    confidenceLevel
    promptScores {
      provenance
      replicability
      objective
      methodology
      publication
      transparency
      overall
    }
    supportingEvidence {
      evidence {
        title
        evidenceType
      }
      weight
      confidence
    }
  }
}

=== Query: Evidence Chain (Graph Traversal)

query {
  evidenceChain(claimId: "claim_1", maxDepth: 3) {
    rootClaim {
      text
    }
    nodes {
      ... on Claim {
        id
        text
      }
      ... on Evidence {
        id
        title
      }
    }
    edges {
      relationshipType
      weight
      confidence
    }
    maxDepth
  }
}

=== Mutation: Create Claim

mutation {
  createClaim(input: {
    investigationId: "uk_inflation_2023"
    text: "Inflation disproportionately affected renters"
    claimType: SUPPORTING
    confidenceLevel: 0.85
    promptScores: {
      provenance: 70
      replicability: 65
      objective: 75
      methodology: 70
      publication: 65
      transparency: 70
    }
  }) {
    id
    text
    promptScores {
      overall
    }
  }
}

=== Mutation: Import from Zotero

mutation {
  importFromZotero(
    investigationId: "uk_inflation_2023"
    zoteroJson: {
      key: "ABC123"
      itemType: "journalArticle"
      title: "New Economic Study"
      url: "https://doi.org/10.1111/example"
      creators: [{name: "Smith, J."}]
      tags: [{tag: "economics"}]
    }
  ) {
    id
    title
    zoteroKey
  }
}

=== Query: Navigation Paths

query {
  navigationPaths(
    investigationId: "uk_inflation_2023"
    audienceType: RESEARCHER
  ) {
    id
    name
    description
    pathNodes {
      entityId
      entityType
      order
      context
    }
  }
}

=== Mutation: Auto-Generate Navigation Path

mutation {
  autoGeneratePath(
    investigationId: "uk_inflation_2023"
    audienceType: SKEPTIC
  ) {
    id
    name
    pathNodes {
      entityId
      order
    }
  }
}

== Project Structure

bofig/
├── lib/
│   ├── evidence_graph/           # Core business logic
│   │   ├── claims/                # Claims context
│   │   │   └── claim.ex
│   │   ├── evidence/              # Evidence context
│   │   │   └── evidence.ex
│   │   ├── relationships/         # Graph edges
│   │   │   └── relationship.ex
│   │   ├── navigation/            # Audience paths
│   │   │   └── path.ex
│   │   ├── arango.ex              # ArangoDB client
│   │   ├── prompt_scores.ex       # PROMPT scoring
│   │   └── application.ex         # OTP supervisor
│   └── evidence_graph_web/        # Phoenix web layer
│       ├── schema/                # GraphQL schema
│       │   ├── types/             # Type definitions
│       │   └── schema.ex          # Root schema
│       ├── endpoint.ex
│       └── router.ex
├── priv/repo/
│   └── seeds.exs                  # UK Inflation 2023 test data
├── config/                        # Environment configs
├── docs/                          # Architecture docs
│   ├── database-evaluation.md
│   └── zotero-integration.md
├── ARCHITECTURE.md                # Data model, API design
├── ROADMAP.md                     # 18-month plan
├── CLAUDE.md                      # AI assistant context
├── Containerfile                  # OCI container build
└── podman-compose.yml             # Container orchestration

== UK Inflation 2023 Test Dataset

The seed data includes a complete investigation:

• 7 Claims (primary, supporting, counter)
• 10 Evidence items (expand to 30)
  • Official statistics: ONS CPI, Ofgem, BoE
  • Academic: Peer-reviewed studies
  • Think tanks: Resolution Foundation, IFS
  • Interviews: Expert opinions
• 10 Relationships (supports/contradicts/contextualizes)
• 3 Navigation Paths:
  1. Researcher: Evidence-first, methodology priority
  2. Policymaker: Authoritative sources, recommendations
  3. Affected Person: Personal impact, clarity

=== PROMPT Score Examples

== Development

=== Run Tests

mix test

=== Interactive Shell

iex -S mix phx.server

= Query ArangoDB directly

iex> EvidenceGraph.ArangoDB.query("FOR c IN claims RETURN c")

= Get a claim

iex> EvidenceGraph.Claims.get_claim("claim_1")

= Evidence chain traversal

iex> EvidenceGraph.Relationships.evidence_chain("claim_1", 3)

=== Code Quality

= Format code

mix format

= Static analysis

mix credo

= Type checking

mix dialyzer

== Deployment (Phase 2)

• Hosting: Hetzner Cloud (EU data sovereignty)
• ArangoDB: ArangoDB Oasis (€45/month)
• Phoenix: Systemd service, Nginx reverse proxy
• CI/CD: GitHub Actions

== Documentation

=== Conceptual (Start Here!)

• link:wiki/index.adoc[Binary-Origami Wiki] - Explains the metaphor and concepts in plain language
• link:wiki/binary-origami.adoc[The Metaphor] - Why "Binary-Origami Figuration"?
• link:wiki/folding-101.adoc[Folding 101] - Hands-on tutorial
• link:wiki/faqs.adoc[FAQ] - Common questions answered
• link:wiki/glossary.adoc[Glossary] - Term definitions

=== Technical

• link:ARCHITECTURE.md[ARCHITECTURE.md] - Data model, database design, API specs
• link:ROADMAP.md[ROADMAP.md] - 18-month implementation plan
• link:docs/database-evaluation.md[docs/database-evaluation.md] - ArangoDB comparison
• link:docs/zotero-integration.md[docs/zotero-integration.md] - Two-way sync design
• link:CLAUDE.md[CLAUDE.md] - AI assistant context

== Key Features

=== Implemented (v1.0.0)

• Multi-model ArangoDB integration (document + graph)
• GraphQL API with Absinthe (15 queries, 11 mutations)
• PROMPT epistemological scoring (6 dimensions, audience weighting)
• Claims, Evidence, Relationships, Navigation Paths data models
• Graph traversal algorithms (evidence chains, shortest path, contradiction detection)
• Zotero REST API (import, export, batch-import, sync-status)
• Phoenix 1.8 LiveView frontend (5 pages: Dashboard, Investigation, Graph, PROMPT, Navigation)
• User authentication (phx.gen.auth with bcrypt, magic links)
• D3.js force-directed graph + radar chart visualisations
• Audience-weighted navigation paths (6 types)
• UK Inflation 2023 test dataset (7 claims, 30 evidence, 38 relationships)
• Production deployment (Containerfile, nginx, systemd)
• NUJ user testing protocols
• A2ML v2.1 Cyberwar-Ready Trustfile
• 257 tests, 0 failures, full RSR compliance

=== Coming Next (Phase 2)

• Zotero browser extension (one-click import)
• Multi-investigation dashboard
• Real-time collaborative editing
• Advanced visualisations (timeline, heatmap, Sankey)
• IPFS provenance integration
• Hetzner Cloud deployment

== Philosophy

This isn't just a database. It's infrastructure for coordinating without consensus.

Every design choice asks:

1. Does this support multiple audience perspectives?
2. Does this make epistemology measurable?
3. Does this enable navigation over narration?

== Contributing

Open source from day 1. See ROADMAP.md for planned features.

Month 3 = Decision Point: User testing with 25 NUJ journalists determines go/no-go.

== Related Projects

• https://github.com/hyperpolymath/formdb[FormDB] - The narrative-first, reversible, audit-grade database
• https://github.com/hyperpolymath/fqldt[FQLdt] - Dependently-typed Form Query Language (compile-time proofs)
• https://github.com/hyperpolymath/formdb-studio[FormDB Studio] - Zero-friction GUI for non-technical users
• https://github.com/hyperpolymath/zotero-formdb[Zotero-FormDB] - Reference manager with PROMPT scores

== License

link:LICENSE[PMPL-1.0-or-later] (Palimpsest License)

== Contact

• Repository: https://github.com/Hyperpolymath/bofig
• Issues: https://github.com/Hyperpolymath/bofig/issues
• User Testing: NUJ network (Month 3, 6, 12)

Built with: Elixir, Phoenix, ArangoDB, Absinthe, LiveView, D3.js

Inspired by: i-docs (PMPL-1.0 Open Doc Lab), Boundary Objects (Star & Griesemer), Pragmatic Epistemology

Last Updated: 2026-02-21

== Architecture

See link:TOPOLOGY.md[TOPOLOGY.md] for a visual architecture map and completion dashboard.