Project Architecture & Pipeline

World Bank D591 · Alliance Bioversity International & CIAT

Visual and conceptual guide to the architecture, data schemas, analytical modules, and evidence-synthesis pipelines of the Rural NbS Scan methodology.

This page provides a comprehensive visual and conceptual guide to the architecture of the NbS Rural Scan project, demonstrating how its architectural layers, analytical modules, data schema, and evidence synthesis pipelines fit together.

1. The Four-Layer Architecture

The project is structured into four distinct layers that separate reusable core code, analytical steps, configurations, and the execution runtime surface.

graph TD
    %% Styling
    classDef primitive fill:#f0f7f4,stroke:#7fd0a1,stroke-width:2px;
    classDef module fill:#fefbf3,stroke:#e4c485,stroke-width:2px;
    classDef recipe fill:#eff2f8,stroke:#9fbbe6,stroke-width:2px;
    classDef runtime fill:#1a1a18,stroke:#c95757,stroke-width:2px,color:#fff;
    
    %% Layer 1: Primitives
    subgraph L1 ["Layer 1: Framework Primitives (Core Engine)"]
        P1["P1: Standardisation (Membership Functions)"]:::primitive
        P2["P2: Weighting (AHP + CRITIC + Entropy)"]:::primitive
        P3["P3: MCDA Engine (Weighted Overlay)"]:::primitive
        P4["P4: Recipe Template Structure"]:::primitive
        P5["P5: Subpractice Variant Patterns"]:::primitive
    end

    %% Layer 2: Modules
    subgraph L2 ["Layer 2: Analytical Modules (Pipeline)"]
        M_M0["M0: Setup & Scope"]:::module
        M_M1["M1: Suitability & Opp Space"]:::module
        M_M2["M2: Rural Climate Risk"]:::module
        M_M3["M3: Characterisation"]:::module
        M_M4["M4: Priority Hotspots"]:::module
        M_M5["M5: Scorecard & Response"]:::module
        M_M6["M6: Hand-off & Next Steps"]:::module
    end

    %% Layer 3: Recipes
    subgraph L3 ["Layer 3: Recipe Layer (Configuration)"]
        R_WH["Water Harvesting Recipe"]:::recipe
        R_AF["Agroforestry Recipe"]:::recipe
        R_FR["Forest Restoration & ANR"]:::recipe
    end

    %% Layer 4: Runtime
    subgraph L4 ["Layer 4: Runtime (Execution Surface)"]
        RT_PKG["Python Method Package (src/nbs_ruralscan/)"]:::runtime
        RT_WIRE["Interactive Wireframe Demonstrator"]:::runtime
        RT_COLAB["Reproducible Colab Notebooks"]:::runtime
    end

    %% Cross-layer links
    L1 -->|Reused by| L2
    L2 -->|Parameterised by| L3
    L3 -->|Executed by| L4
    R_AF -->|Supplies variables & bounds| RT_PKG

2. The Analytical Module Pipeline (M0–M6)

The World Bank Task Team Leaders (TTLs) consume the scoping tool through a linear pipeline of seven modules, plus a parallel project risk addendum (M2b).

graph TD
    %% Styling
    classDef start_card fill:#eef2f3,stroke:#94a3b8,stroke-width:2px;
    classDef module fill:#fff,stroke:#e2e8f0,stroke-width:2px;
    classDef risk fill:#fef2f2,stroke:#f87171,stroke-width:2px;
    
    %% Modules
    M0["M0: Setup & Scope 
 (Pete) 
 [T0, T1, T7]"]:::module
    M1["M1: Opportunity Space 
 (Pete) 
 [T1, T4, T7]"]:::module
    M2["M2: Rural Climate Risk 
 (Brayden) 
 [T1, T2]"]:::module
    M2b["M2b: Project Risk Screen 
 (Brayden) 
 [T1, T2, T3, T7]"]:::risk
    M3["M3: Characterisation 
 (Pete) 
 [T1, T5]"]:::module
    M4["M4: Hotspots (MCDA) 
 (Pete) 
 [T5]"]:::module
    M5["M5: Scorecard & Response 
 (Namita) 
 [T3, T6]"]:::module
    M6["M6: Hand-off & Next Steps 
 (Namita / MFL) 
 [T0, T6]"]:::module

    %% Flows
    M0 -->|AOI & Scope| M1
    M1 -->|Opportunity Space Layer| M2
    M1 -->|Opportunity Space Layer| M3
    
    %% M2 to M2b branching
    M2 -->|Livelihood Risk Need| M4
    M2 -->|Asset Exposure / Levers| M2b
    
    M3 -->|Thematic Priorities| M4
    
    %% M2b as a filter on Hotspots
    M2b -.->|Screening Filter / Flag| M4
    
    M4 -->|Priority Hotspots Map| M5
    M5 -->|Scorecard Metrics| M6

Module Descriptions & Table Bindings

M0: Setup & Scope: Selects the Area of Interest (AOI), target NbS, resolution, and baseline context. Matches T0 (NbS Registry), T1 (Data Registry), and T7 (Geographic Context).
M1: Suitability → Opportunity Space: Models biophysical constraints (e.g., slope, elevation, temperature) using fuzzy membership functions and MCDA overlay. Outputs the continuous opportunity space map. Consumes T4 (Suitability Mappings).
M2: Rural Climate Risk: Evaluates climate hazards, exposure, and adaptive capacity to assess threat to rural livelihoods (a "need" layer). Consumes T2 (Climate Risk).
M2b: Project Disaster-Risk Screen: Assesses risk to the investment itself (Stream A: establishment hazard exposure; Stream B: enabling environment/tenure safeguards). Filters or flags hotspots, but is never summed directly with livelihood risks. Consumes T3 (Hazard/Farming) and T7 (Geographic Context).
M3: Opportunity Space Characterisation: Overlays thematic priorities (poverty, biodiversity, population) to describe the area. Consumes T5 (Opportunity Space Priorities).
M4: Priority Hotspots: Performs user-weighted multi-criteria decision analysis (MCDA) to locate high-priority areas within the suitability space.
M5: NbS Scorecard & Response: Summarizes economics, cost-effectiveness denominators (e.g., establishment costs, recurrent costs), and benefits. Consumes T6 (NbS Scorecard).
M6: Hand-off & Next Steps: Generates hand-off tool options, legal/exclusion safeguard alerts (ESS7 flags), and context-specific tailoring guidelines.

3. Data Schema (T0–T7) and Content-Code Contract

The analytical rules, weights, and dataset bindings are never hardcoded. The system uses a machine-validated database schema where the runtime code queries these tables for execution.

graph TD
    %% Styling
    classDef registry fill:#e1f5ee,stroke:#085041,stroke-width:2px,color:#085041;
    classDef table fill:#f8fafc,stroke:#cbd5e1,stroke-width:2px;
    
    T0["T0: NbS Registry"]:::registry --> T4["T4: Suitability Mappings"]:::table
    T0 --> T6["T6: NbS Scorecard"]:::table
    T4 --> T7["T7: Geographic Context"]:::table
    T6 --> T3["T3: Hazard & Farming Link"]:::table
    T7 --> T1["T1: Data Registry"]:::table
    T3 --> T1

4. The Evidence-to-Synthesis Pipeline

For each recipe (such as Agroforestry), rules are compiled from empirical literature using our evidence registers. The runtime synthesis engine parses these registers and builds the final schema tables.

graph TD
    %% Styling
    classDef reg fill:#fff5f5,stroke:#ff8a8a,stroke-width:2px;
    classDef script fill:#f0fdf4,stroke:#4caf72,stroke-width:2px;
    classDef out fill:#f0f9ff,stroke:#0284c7,stroke-width:2px;

    %% Data Ingestion
    LIT["Empirical Literature 
(Systematic Reviews, PADs, Journals)"] -->|PDF Ingest & Indexing| CACHE_PDF[".cache/ingest/ 
(Clean text & table cache)"]
    
    NON_PDF["Non-PDF Sources 
(WOCAT SLM, ICRAF Tree DB, GitHub Repos, LandMark)"] -->|API Pull, Scrape, Clone, DB Export| CACHE_RAW[".cache/ingest/ 
(Raw JSON, Scraped text, Scripts)"]
    
    %% AI Extraction
    CACHE_PDF & CACHE_RAW -->|Extraction Contracts & Parsing| EXT["Extraction Engine 
(source-command-extract-evidence / structured parser)"]
    
    %% Registers
    EXT -->|Structured claim records| EV["EV_evidence_register.json / .csv 
 (Verbatim thresholds, contexts, and quotes)"]:::reg
    LIT & NON_PDF -->|Metadata, AEZ, & baseline status| SRC["SRC_source_register.json / .csv 
 (Track variables and validation state)"]:::reg
    
    %% Synthesis Script
    EV & SRC -->|Read by| SYN["execute_synthesis.py 
 (Synthesis & Reconciliation Engine)"]:::script
    
    %% Target Tables
    SYN -->|Calculate weighted medians & support rates| T4["T4_suitability_mappings.json / .csv"]:::out
    SYN -->|Resolve citations & map hazards| T3["T3_nbs_hazard_farming.json / .csv"]:::out
    SYN -->|Link Likert effects & resolve economic indicator costs| T6["T6_nbs_scorecard.json / .csv"]:::out

Consensus Weighting Rules: During synthesis, evidence lines are collapsed back to their ultimate primary study to prevent double-counting. The synthesis engine automatically derives threshold bounds, calculates the percentage of literature support (paper_support_pct), and measures uncertainty spreads across all registered biophysical variables.

5. Ingestion & Synthesis Progress Dashboard

How the Evidence-to-Synthesis Pipeline fits into our broader project development lifecycle. Literature is systematically discovered and swept into registers before compiling into the schema recipes that drive spatial execution.

graph TD
    %% Ingest flow
    LIT["Empirical Literature 
(Reviews, PADs, Journals)"] -->|PRISMA funnel query & triage| SRC_P["SRC Register 
(status: pending)"]
    NON_PDF["Non-PDF Sources 
(Tools, DBs, Web Platforms, Repos)"] -->|Database query, scrape & triage| SRC_P
    
    SRC_P -->|Extraction Contracts / Parsing| EV_REC["EV Register 
(Verbatim quotes, thresholds, and economic stats)"]
    SRC_P -->|Metadata validation| SRC_S["SRC Register 
(status: swept)"]
    SRC_S & EV_REC -->|Schema compiler: generate.py| REC_JSON["JSON Recipes 
(T3, T4, T6 compiled rules)"]
    REC_JSON -->|runtime/binding.py resolver| BIND_RESOLVE["Context-Resolved Variables for AOI"]
    BIND_RESOLVE -->|M0-M6 Pipeline Runtime| OUT["Spatial Opportunity & Hotspots Map"]
    
    %% Styling
    classDef reg fill:#fff5f5,stroke:#ff8a8a,stroke-width:2px;
    classDef script fill:#f0fdf4,stroke:#4caf72,stroke-width:2px;
    classDef out fill:#f0f9ff,stroke:#0284c7,stroke-width:2px;
    
    class EV_REC,SRC_P,SRC_S reg;
    class REC_JSON,BIND_RESOLVE script;
    class OUT out;

To inspect real-time ingestion statistics, view verbatim evidence claims, biophysical parameters, and scorecard economics, please visit the dedicated dashboard.

Interactive Evidence Interrogation: Explore the Evidence & Literature Interrogation Dashboard to see the source registers, evidence mappings, and recipe tables compiled in real-time.