# Technical architecture

```
index.html
  styles.css          UI design, responsive layout
  engine.js           Pure deterministic estimators, API normalization, CSV
  demo-data.js        Explicitly synthetic 3,000-row teaching panel
  app.js              State management, graphs, navigation, exports, API fetch

README.md             Hugging Face Space frontmatter: sdk: static
METHODOLOGY.md        Specifications and assumptions
DATA_DICTIONARY.md    Published indicator codes
PROVENANCE.md         Source attribution and session rules
QA_REPORT.md          Build-time tests and known limitations
test_engine.cjs       Node test runner
test_browser.py       Chromium browser smoke checks
```

## Design decisions

* Vanilla JavaScript avoids server compute, secret-bearing API proxies and heavyweight install steps.
* The rendering layer is separated from estimator functions, which are dependency-free and directly tested under Node.
* SVG charts are generated client-side, with accessible labels and per-point hover descriptions.
* Session JSON stores inputs and data observations to reproduce the comparison locally. It does not claim cryptographic source authenticity.
* World Bank API calls use a fixed set of indicator codes and ISO3 economies, with a request timeout and clearly signaled network errors.
* Synthetic control optimization is implemented using projected gradient on the probability simplex, with an explicit regularization coefficient.

## Known trade-offs

This browser-only edition does not implement advanced R packages, high-dimensional panel estimators, randomized inference, causal graph learning, APIs with authentication, or persistent user storage. These would require a separate, tested backend edition and a different hosting/cost strategy.