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