# 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.