ARCHITECTURE.md

Architecture

Why a static browser application?

Hugging Face Static Spaces hosts an index.html entry point and relative JS/CSS without an always-running server. The five runtime files use only first-party browser APIs and ES modules, so there is no recurring compute cost, subscription, model endpoint, or API key.

Modules

• index.html defines layout, navigation and seven panel slots.
• styles.css defines palette, mobile view, SVG canvas and accessible UI states.
• engine.js contains pure deterministic functions for bibliographic parsing, numeric observation extraction, DOI normalization, graph validation, summaries, path finding, XML/CSV/Markdown exports.
• demo.js contains all fictional demonstration records. These are explicitly marked synthetic.
• app.js manages the in-memory session, renders escaped DOM templates, handles user forms and external fetch calls, and creates downloadable Blob files.

Data flow

Crossref public metadata or manual publication → publication node
World Bank observation or manually sourced data → indicator node
Researcher-defined assertion → claim / hypothesis node
Exact passage + locator + review status → relationship edge
Evidence graph → audits / visualization / exports

No external publication record is automatically converted into a research claim. Network relations are authored by researchers, not inferred by an LLM.

Graph format

{nodes: [{id, kind, title, ...}], links: [{id, from, to, relation, excerpt, locator, review, ...}]}

• Four node types: publication, indicator, claim, hypothesis.
• Three directional relations: supports, challenges, context.
• Maximum imported graph: 300 nodes / 700 links; JSON file limit 2 MB.
• DOI duplicates are prevented when added via public metadata.
• SVG network uses deterministic type columns and allows node inspection.
• Shortest path follows links in either direction, for relationship discovery only.

Reproducibility

Portable JSON is versioned with schemaVersion: 1, includes full node and link arrays, session notes, demo provenance, and exported timestamp. Additional exports are independent CSV/GraphML and a human-readable Markdown methods brief.