Compare ecological interventions and visualize likely habitat trajectories over 5 years — built for homeowners and schools.
- Scenario Comparison: Compare native meadow vs rain garden vs shrub border side-by-side
- 5-Year Trajectories: Pollinator diversity, bird activity, food-web complexity, ecosystem services
- Logistic Growth Curves: Ecologically realistic diminishing returns — no metric falsely saturates to 1.0
- Multi-Intervention Synergy: Combining meadow + nesting + structures yields measurable per-metric boosts (up to 62% pollinator synergy)
- Soil-Aware Modelling: Clay boosts rain gardens (+15% services), penalises meadows (−12% pollinators) — 4 soil types × 8 interventions
- Bloom Continuity Score: Shannon-entropy metric quantifying how evenly bloom coverage spans the growing season
- Succession-Aware Bloom: Year-by-year bloom calendars model which species establish first (forbs before shrubs)
- Shannon-Wiener Diversity Index: Real ecological diversity (H') and Pielou evenness (J') computed from the food web
- Uncertainty-First: Every projection shows optimistic / likely / conservative bands with confidence scores
- AI-Powered Narratives: OpenAI explains ecological outcomes and recommends species
- Interactive Food Web: Watch your ecosystem grow from bare soil to a thriving network
- Actionable Output: Printable planting calendars, shopping lists, and month-by-month guides
flowchart LR
subgraph User Journey
A["🏠 Enter ZIP Code\n+ Site Details"] --> B["🔬 Choose\nInterventions"]
B --> C["📊 Compare\nTrajectories"]
C --> D["📋 Get Action\nPlan"]
end
subgraph Backend Pipeline
E["ZIP Lookup\nUSDA Zone + EPA Ecoregion"] --> F["Succession Engine\n5-Year Trajectories"]
F --> G["Uncertainty Layer\nConfidence Bands"]
G --> H["AI Reasoner\nNarrative + Species"]
F --> I["Food Web Builder\nTrophic Network"]
F --> J["Bloom Calendar\nMonthly Schedule"]
G --> K["Action Plan\nPlanting Calendar"]
end
A -.->|/api/lookup| E
B -.->|/api/simulate| F
D -.->|/api/action-plan| K
| Step | Screen | What Happens |
|---|---|---|
| 1 | 🧙 Site Wizard | ZIP → auto-detect USDA zone + ecoregion → enter area, sun, soil, goals |
| 2 | 🔬 Interventions | Browse scored interventions → select 1-3 to compare |
| 3 | 📊 Dashboard | Trajectory charts + food web + bloom calendar + AI narrative |
| 4 | 📋 Action Plan | Month-by-month planting calendar + shopping list + printable PDF |
When homeowners want to rewild their yard:
- Pollinator garden selectors give static plant lists — no trajectory over time
- AI landscape tools show how it looks — not how the ecology evolves
- Research simulators require institutional expertise to operate
- No tool answers: "If I plant a native meadow vs a rain garden, what happens to pollinators in Year 3?"
REWILD is a consumer ecological scenario engine that:
- Ingests your location + site description (ZIP → USDA zone + EPA ecoregion)
- Simulates ecological trajectories for each intervention over 5 years
- Compares scenarios with uncertainty bands so you see the range of outcomes
- Generates personalized planting calendars and action plans
graph TB
subgraph Frontend ["Frontend · React 19 + Vite"]
W["SiteProfileWizard"] --> IP["InterventionPanel"]
IP --> D["Dashboard"]
D --> AP["ActionPlan"]
D --> TC["TrajectoryChart · Recharts"]
D --> FW["FoodWebGraph · Canvas 2D"]
D --> CP["ConfidencePanel"]
end
subgraph APILayer ["API Layer · FastAPI + Uvicorn"]
L["/api/lookup/{zip}"]
S["/api/simulate"]
A["/api/action-plan"]
end
subgraph DataLayer ["Data Layer · Curated Ecological Datasets"]
UZ["USDA Hardiness Zones\n3-digit ZIP → Zone"]
ER["EPA Ecoregions\nLevel III classification"]
NP["Native Plants DB\nSpecies by ecoregion"]
PO["Pollinator Registry\nBees, butterflies, birds"]
IV["Intervention Library\n8 conversion types"]
end
subgraph SimEngine ["Simulation Engine"]
SE["Succession Model\n5-year trajectories"]
UE["Uncertainty Engine\nConfidence bands"]
BC["Bloom Calendar\nMonthly phenology"]
FWB["Food Web Builder\nTrophic network"]
APG["Action Plan Generator\nPlanting calendar"]
end
subgraph AILayer ["AI Layer"]
GPT["OpenAI GPT-4o-mini\nEcological Narratives"]
FB["Template Fallback\nOffline-capable"]
end
Frontend -->|"Vite Proxy /api/*"| APILayer
L --> DataLayer
S --> SimEngine
A --> APG
SimEngine --> DataLayer
SE --> UE
UE --> GPT
GPT -.->|"API failure"| FB
sequenceDiagram
participant U as User
participant FE as Frontend
participant API as FastAPI
participant DL as Data Layer
participant SE as Succession Engine
participant UE as Uncertainty Engine
participant AI as OpenAI GPT-4o
participant FW as Food Web Builder
Note over U,FW: Phase 1 — Site Profile
U->>FE: Enter ZIP code
FE->>API: GET /api/lookup/75254
API->>DL: Query USDA zones + EPA ecoregions
DL-->>API: Zone 8a, Great Plains, TX
API-->>FE: Site profile data
FE-->>U: Display zone, ecoregion, frost dates
Note over U,FW: Phase 2 — Simulation
U->>FE: Select interventions + Run
FE->>API: POST /api/simulate
par Parallel Processing
API->>SE: simulate_trajectory() per intervention
SE-->>API: 5-year metric arrays
API->>UE: wrap_with_uncertainty()
UE-->>API: Optimistic/likely/conservative bands
API->>FW: build_food_web()
FW-->>API: Nodes + edges per year
end
API->>AI: get_narrative() with metrics
AI-->>API: Ecological narrative + species list
API-->>FE: Complete simulation payload
FE-->>U: Interactive dashboard
Note over U,FW: Phase 3 — Action Plan
U->>FE: Request action plan
FE->>API: POST /api/action-plan
API-->>FE: Calendar + shopping list + tasks
FE-->>U: Printable action plan
The deterministic succession engine simulates 4 ecological metrics over 5 years using logistic growth curves:
| Metric | Year 0 | Year 5 | What It Measures |
|---|---|---|---|
| Pollinator Diversity | 0.05–0.15 | 0.45–0.85 | Shannon diversity index of pollinator species |
| Bird Activity | 0.05–0.15 | 0.30–0.60 | Relative bird visitation and habitat-use potential |
| Food-Web Complexity | 0.03–0.10 | 0.35–0.80 | Relative trophic-network richness and connectivity |
| Ecosystem Services | 0.05–0.15 | 0.40–0.75 | Composite: water filtration, erosion control, air quality |
Instead of linear v × modifier (which overflows past 1.0 and must be clamped), modifiers are applied through a logistic curve:
This naturally compresses near the ceiling — the same way real ecosystems exhibit diminishing returns as they approach carrying capacity. Example: the old model gave 0.75 × 1.25 × 1.3 = 1.22 → clamped to 1.0 (a false "perfect" ecosystem); the new model yields 0.692 — a realistically high but non-saturated score.
Each ecological metric responds differently to site factors:
| Factor | Pollinator | Bird | Food Web | Services |
|---|---|---|---|---|
| Area | 0.8× | 1.4× | 1.0× | 1.2× |
| Sun | 1.3× | 0.8× | 1.0× | 0.9× |
| Soil | 0.9× | 0.7× | 0.8× | 1.4× |
Birds care more about territory size; pollinators care more about sunlight; ecosystem services care more about soil quality.
Soil type interacts with each intervention differently across all 4 metrics:
| Soil × Intervention | Impact |
|---|---|
| Clay + Rain Garden | +15% services, +10% pollinators (clay retains water → rain gardens excel) |
| Clay + Native Meadow | −12% pollinators, −15% food web (compacted clay limits root establishment) |
| Sandy + Rain Garden | −22% services (water drains too fast for rain garden effectiveness) |
| Sandy + Pollinator Nesting | +5% pollinators (sandy soil is ideal for ground-nesting bees) |
compute_synergy() examines all pairwise combinations among selected interventions and multiplies per-metric synergy coefficients:
| Combination | Poll | Bird | Web | Svc |
|---|---|---|---|---|
| Meadow + Nesting | 1.25 | 1.05 | 1.18 | 1.08 |
| Meadow + Structures | 1.10 | 1.20 | 1.15 | 1.12 |
| Shrub + Structures | 1.08 | 1.22 | 1.15 | 1.10 |
| Meadow + Nesting + Structures | 1.62 | 1.45 | 1.56 | 1.31 |
18 pairwise synergies are defined. Triple-intervention synergy is the product of all 3 pair coefficients.
Trajectories are additionally modulated by:
- Ecoregion multipliers — Tropical Florida (1.3×) recovers faster than Northern Forests (0.85×)
- USDA zone factors — Growing season length affects establishment rates
- Current site state — Partial gardens (1.25×) have a head start over bare soil (0.85×)
- Intervention type — Each of the 8 interventions has unique 6-year base curves
Every metric value is wrapped with confidence bands:
┌─ Optimistic (base × 1.25)
│
══════════════════╪══════════════════ ← Likely (base value)
│
└─ Conservative (base × 0.75)
Confidence: 85% (Year 1) → 60% (Year 5)
Band width widens with time, narrows with more site data
Uncertainty reducers — actionable suggestions that narrow the bands:
- "Add a soil test to narrow ecosystem service predictions by ~15%"
- "Confirm sun hours to improve pollinator diversity estimates"
- "Report first-year observations to calibrate Year 2+ projections"
Generates a year-by-year trophic network with 3 levels:
| Level | Examples | Source |
|---|---|---|
| Top Consumers | Meadowlark, Chickadee, Goldfinch | Bird species for ecoregion |
| Consumers | Monarch, Bumblebee, Swallowtail | Pollinator registry |
| Producers | Coneflower, Milkweed, Bluestem | Native plant database |
- Network grows from ~3 nodes (Year 0) to ~34 nodes (Year 5)
- Edges represent directed feeding/pollination relationships
- Conservation status highlighted (declining species get red borders)
Each year's food web includes two standard ecological diversity metrics:
-
Shannon-Wiener Index (H') —
$H' = -\sum p_i \ln(p_i)$ — measures species diversity weighted by abundance. Rises from ~1.0 (Year 0) to ~3.2 (Year 5) for a typical meadow. -
Pielou's Evenness (J') —
$J' = H' / \ln(S)$ — normalised to [0, 1], where 1.0 means all species are equally abundant. Typical values: 0.90–0.95. -
Directed Connectance —
$C = E / N(N-1)$ — corrected from the old undirected formula. Trophic graphs are inherently directional (plants don't eat pollinators).
| Year | Nodes | Edges | H' | J' | Connectance |
|---|---|---|---|---|---|
| Y0 | 3 | 2 | 1.04 | 0.95 | 0.333 |
| Y1 | 9 | 10 | 2.10 | 0.95 | 0.139 |
| Y3 | 22 | 31 | 2.82 | 0.91 | 0.067 |
| Y5 | 34 | 50 | 3.16 | 0.90 | 0.045 |
A temporal bloom calendar that evaluates how evenly a garden blooms across 12 months using a normalized Shannon-entropy metric (Bloom Continuity Score).
Because the engine is succession-aware, it models when plants establish—fast-growing forbs bloom in Year 1, while slow-growing shrubs and trees don't provide bloom coverage until Year 3+. It also analyzes temporal gaps and automatically recommends specific native species to fill "low-bloom" months.
Two-tier AI system with graceful degradation:
| Tier | Provider | When Used | Response Time |
|---|---|---|---|
| Primary | OpenAI GPT-4o-mini | API key configured | ~2 seconds |
| Fallback | Template engine | No key / API failure | Instant |
The AI generates:
- Narrative — 2-3 paragraph ecological story explaining outcomes
- Species recommendations — Top 5 native species with rationale
- Key insight — One surprising ecological outcome
Produces frost-date-aware planting calendars:
| Component | Details | |-----------|---------|| | Planting Calendar | 12 months × species, tied to last/first frost dates | | Prep Tasks | 8-week site preparation timeline | | Shopping List | Species × quantity, calculated from area + density | | Maintenance | Seasonal checklists for year-round care | | Mistakes to Avoid | Top 10 common errors with ecological reasoning |
| Layer | Technology | Purpose |
|---|---|---|
| Frontend | React 19 + Vite 7 | 4-screen wizard → dashboard flow |
| Charts | Recharts 3 | Trajectory timelines with confidence band areas |
| Visualization | Canvas 2D API | Hierarchical food web with animated year progression |
| Backend | FastAPI + Uvicorn | Async REST API and simulation orchestration |
| AI | OpenAI GPT-4o-mini | Ecological narratives + species recommendations |
| Data | Curated Python datasets | USDA zones, EPA ecoregions, native plants, pollinators |
| Package Mgmt | uv (backend) · npm (frontend) | Fast, reliable dependency management |
- ZIP code → automatic USDA hardiness zone + EPA ecoregion lookup
- Site conditions: current state, sun exposure, soil type
- Goal selection: pollinators, birds, water management, carbon, beauty
- Logistic succession model: 5-year trajectories for 4 key metrics with ecologically realistic diminishing returns
- Multi-intervention synergy: Combining interventions yields measurable per-metric boosts (18 pairwise synergies)
- Soil-aware modelling: Clay, sandy, loamy, and well-drained soils interact differently with each intervention
- Per-metric sensitivity: Area helps birds most (1.4×), sun helps pollinators most (1.3×), soil helps services most (1.4×)
- Uncertainty propagation: Confidence bands widen with time, narrow with data
- Food web + diversity: Plant → pollinator → bird trophic network with Shannon-Wiener H' and Pielou evenness J'
- Bloom continuity: Shannon-entropy score (0–1) measuring how evenly bloom coverage spans the year
- Succession-aware bloom: Year-by-year bloom calendars model forb-before-shrub establishment order
- Gap-filling recommendations: Suggests species to fill months with no bloom coverage
- Overlay mode: Compare all scenarios on one chart
- Side-by-side mode: Individual charts per intervention
- Metric tabs: Pollinator diversity, bird activity, food-web complexity, ecosystem services
- Food web animation: Play 5-year growth from bare soil to complex ecosystem
- Planting calendar: Month-by-month tasks tied to your frost dates
- Shopping list: Species with quantities calculated for your area
- Prep tasks: Week-by-week site preparation guide
- Seasonal maintenance: Spring / summer / fall / winter checklists
- Common mistakes: What NOT to do (and why)
- Print to PDF: Take your planting calendar to the garden center
- Python 3.13+ with uv
- Node.js 20+
- OpenAI API key (optional — works without it via fallback narratives)
git clone https://github.com/your-repo/rewild.git
cd rewild# Backend
cd backend
uv sync
# Frontend
cd ../frontend
npm install# Optional: Add OpenAI key for AI-powered narratives
cp backend/.env.example backend/.env
# Edit backend/.env and add: OPENAI_API_KEY=your_key_here# Terminal 1 — Backend
cd backend
uv run uvicorn app.main:app --port 8000
# Terminal 2 — Frontend
cd frontend
npm run dev| Service | URL |
|---|---|
| App | http://localhost:5173 |
| API | http://localhost:8000 |
| API Docs | http://localhost:8000/docs |
- Enter ZIP 75254 → Look Up → Area 1000 sq ft → Continue
- Select Maintained Lawn · Full Sun · Well-drained → Continue
- Check Support Pollinators + Natural Beauty → See Interventions
- Select Native Meadow + Rain Garden → Run Scenario Engine
- Toggle Side by Side → switch metrics → play food web animation
- Click Get Your Action Plan → → browse 5 tabs → 🖨️ Print
| Method | Endpoint | Description |
|---|---|---|
GET |
/health |
Health check |
GET |
/api/lookup/{zip} |
USDA zone + EPA ecoregion lookup |
GET |
/api/interventions |
List available interventions |
GET |
/api/plants/{ecoregion} |
Native plants for ecoregion |
GET |
/api/pollinators/{ecoregion} |
Pollinators for ecoregion |
POST |
/api/simulate |
Run full simulation pipeline |
POST |
/api/action-plan |
Generate planting calendar + action plan |
rewild/
├── backend/
│ ├── app/
│ │ ├── data/ # Curated ecological datasets
│ │ │ ├── usda_zones.py # Hardiness zone lookup (3-digit ZIP)
│ │ │ ├── ecoregions.py # EPA Level III ecoregion mapping
│ │ │ ├── native_plants.py # Native species by ecoregion
│ │ │ ├── pollinators.py # Pollinator species data
│ │ │ └── interventions.py # Intervention definitions
│ │ ├── engine/ # Simulation engine
│ │ │ ├── succession.py # Logistic trajectory model + synergy + soil effects
│ │ │ ├── bloom_calendar.py # Bloom calendar + continuity score + succession bloom
│ │ │ ├── interactions.py # Food web + Shannon-Wiener diversity index
│ │ │ ├── uncertainty.py # Confidence bands + reducers
│ │ │ ├── claude_reasoner.py # OpenAI narrative generator
│ │ │ └── action_plan.py # Planting calendar generator
│ │ ├── routes/ # API endpoints
│ │ │ ├── lookup.py # Location lookup routes
│ │ │ └── simulate.py # Simulation + action plan routes
│ │ └── main.py # FastAPI app entry point
│ └── pyproject.toml
├── frontend/
│ ├── src/
│ │ ├── SiteProfileWizard.jsx # 3-step site profile wizard
│ │ ├── InterventionPanel.jsx # Intervention selection + scoring
│ │ ├── Dashboard.jsx # Main dashboard orchestrator
│ │ ├── TrajectoryChart.jsx # Recharts trajectory visualization
│ │ ├── FoodWebGraph.jsx # Canvas food web network
│ │ ├── ConfidencePanel.jsx # AI narrative + uncertainty panel
│ │ ├── ActionPlan.jsx # 5-tab action plan with print
│ │ ├── App.jsx # Root component with routing
│ │ └── App.css # Complete design system
│ ├── package.json
│ └── vite.config.js # Proxy config for /api/*
├── .env.example
├── .gitignore
├── LICENSE # MIT
└── README.md
| Variable | Required | Description |
|---|---|---|
OPENAI_API_KEY |
No | OpenAI API key for AI narratives (falls back to templates) |
- Logistic over linear: Ecological growth naturally exhibits diminishing returns near carrying capacity — the logistic curve models this without artificial clamping
- Shannon-Wiener over Simpson's: H' is more sensitive to rare species — critical for a conservation-focused tool
- Directed connectance: Trophic graphs are inherently directed (plants → pollinators → birds), so
C = E / N(N−1)is used instead of the undirected formula - Per-metric weights: Not all metrics respond equally to all factors — area matters most for birds (territory), sun matters most for pollinators (foraging)
- Synergy as pairwise products: Synergy coefficients multiply across pairs, naturally scaling with the number of complementary interventions
- Uncertainty-first: Every metric shows range bands, not point predictions
- Offline-capable AI: Works fully without an API key using template narratives
- Ecoregion-aware: All data is localised to EPA Level III ecoregions
- Intervention comparison: Side-by-side comparison is a first-class feature
- Printable output: Action plans designed for printing and taking to the garden
- Stateless & Database-free Architecture: By cleanly curating and embedding ecological datasets directly into the API layer, the backend is 100% stateless, offering infinite scalability and zero database management.
While REWILD is free for individual homeowners, the underlying engine has clear paths to sustainability:
- B2B Licensing for Nurseries: Garden centers can embed REWILD on their sites to drive hyper-local, ecologically appropriate plant sales.
- Municipal & School District Tiers: Pro dashboards for cities tracking their biodiversity goals across public lands and schools.
- NGO Partnerships: Whitelabeling the tool for conservation groups to power their specific regional rewilding campaigns.
MIT License — see LICENSE file for details.
Built for DevDash 2026
Compare what happens under different scenarios, see the likely range of outcomes, and learn what to observe.