README.md

metadata

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

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.