Blame for README.md

---
title: CircularFlow
emoji: ♻️
colorFrom: green
colorTo: blue
sdk: static
app_file: index.html
pinned: false
license: mit
short_description: Circular economy and recovery simulation.
---

# CircularFlow

### Circular Economy Intelligence Studio | Hugdrigo Portfolio Project #104

**CircularFlow** is a local-first, self-contained material circularity and recovery simulation studio for illustrating portfolio waste flows, recovery economics, and scenario-dependent avoided-impact proxies. The application runs directly in the browser as a static Hugging Face Space.

**Short description:** Circular economy and recovery simulation.

> **Demo only.** All initial facilities, material streams, quantities, process yields, cost parameters and environmental factors are invented. Results are not measurements, certified greenhouse-gas reductions, a compliant lifecycle assessment, or forecasts.

## Publish on Hugging Face

1. Open [Create a Space](https://huggingface.co/new-space).
2. Choose the owner **`Hugdrigo`** and the name **`circularflow-material-intelligence`**.
3. Select **Static** SDK, **Blank** template, **Public** visibility and **MIT** license.
4. Upload `README.md`, `index.html`, and `LICENSE` into the *root* of the Space. Leave the YAML frontmatter in this README unchanged.
5. Open the Space and test navigation, scenario sliders, adding/editing/archiving a stream, a CSV export, a JSON backup and a JSON restore.

The application has **no external dependencies**, API keys, backend, remote requests, trackers, paid services, or GPU requirements. Data are stored in browser `localStorage` if permitted; use JSON backup to transfer data between devices.

## Main features

| Module | Capability |
|---|---|
| Overview | Portfolio generated / diverted / recovered material, net variable costs, indicative impact, 12-month illustrative seasonal chart, material ranking |
| Scenario Lab | Four preset operating scenarios, editable volume/diversion/contamination/resale changes, baseline comparison and stream-level impact |
| Material Registry | Eight synthetic sample material streams, edit/add up to 200 records, searchable registry, archive/restore, JSON backup/restore, CSV export |
| Impact Analysis | Mass-balance reconciliation, economic detail, emissions proxy, per-stream comparison |
| Methodology | Explicit equations, assumptions, scope exclusions, environmental and privacy disclaimers |

## Key definitions

A **month** is the time unit. Material volumes are tonnes (t), and money is nominal USD equivalent, not real-time prices.

For each active material stream:

```text
G = generated tonnes in the modeled month
D = G × diversion percentage / 100
C = contamination percentage / 100
Y = recovery yield percentage / 100
R = D × (1 − C) × Y
W = G − R

Disposal cost       = W × disposal cost per tonne
Processing cost     = D × processing cost per tonne
Recovered revenue   = R × resale value per tonne
Net cost            = disposal cost + processing cost − recovered revenue
Net emission proxy  = R × avoided-impact factor − D × processing-impact factor
```

`G = R + W` is enforced by construction. **Diverted** does not mean **recovered**. Materials rejected in processing remain within the modeled unrecovered residual. This simplifies real-world streams and does not describe specific landfill / recycling plant operations.

### Scenario modifiers

| Preset | Volume | Diversion | Contamination | Resale price |
|---|---:|---:|---:|---:|
| Current operations | 0% | 0 pp | 0 pp | 0% |
| Collection upgrade | 0% | +17 pp | −3 pp | 0% |
| Quality improvement | 0% | +6 pp | −9 pp | +7% |
| Commodity downturn | +14% | −8 pp | +11 pp | −35% |

Custom control values are clamped to the supported ranges. Diversion and contamination percentages are clamped to `[0,100]`. For every scenario, the unchanged baseline uses the same original active records. The monthly chart on Overview is **illustrative** and scales the baseline by a fixed seasonal pattern, not a statistical forecast.

### Environmental limitations

Avoided-impact factors and processing-impact factors are fictional, manually editable tCO₂e/t proxy coefficients. The implied result excludes upstream supply chain emissions, alternative disposal pathways, material market substitution assumptions, transportation, landfill methane, scope boundaries and real-life processing energy and cannot be interpreted as independently verified emissions savings. Monetary calculations likewise omit capital expenditure, taxes, logistics, fixed overhead and financing.

## Data handling and validation

- JSON format: `{ "project":"CircularFlow", "version":1, "records":[...], "scenario":"baseline", "settings":{...} }`.
- Data restoration validates recognized categories, allowed value ranges, unique IDs, required strings and scenario settings before applying any replacement. Maximum 200 records, maximum 350 KB JSON upload.
- Data entry and imported names are displayed with HTML escaping.
- CSV fields are quoted; leading spreadsheet formula characters are escaped to reduce spreadsheet injection risk. Still review exports before opening them in third-party spreadsheet software.
- Archiving does not delete data. The **Reset demo** button does replace local data after confirmation: export a backup first.
- localStorage availability depends on the browser and origin. JSON exports are portable; the hosted Space does not receive your saved local state.
- Use fictional or non-sensitive sample data for public demos. Real deployment requires site-specific input validation, internal privacy controls, expert environmental methodology, and independent validation.

## Project files

- `index.html`: complete app, styles, and all JavaScript. Works without an install step.
- `README.md`: Space metadata, publication instructions and transparent methodology.
- `LICENSE`: MIT license.

Copyright (c) 2026 Hugdrigo. MIT licensed.