# oliversinn/polio-risk architecture

> Architecture diagram of the GitHub repository oliversinn/polio-risk, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/oliversinn/polio-risk
- Repository: https://github.com/oliversinn/polio-risk

## Overview

##### Overview of the Project Type and Purpose
- This project is an R-based analytical tool for assessing the risk of polio outbreaks. Its core functionality centers on data handling, geospatial processing (using shapefiles), risk evaluation, dashboard visualization, and report generation.

##### Analyzing the File Structure – Key Directories and Files
- Top-Level Files:
- Files like .Rprofile, README.md, install.R, and the .Rproj file provide the project’s configuration and startup.
- The renv directory indicates dependency management, so include an “Environment & Dependencies” block.
- Data Layer:
- The “src/Data” directory holds the country data (Excel files) and shapefiles (admin2.* files) used for mapping.
- The “template” directory contains language-specific templates for data input.
- R Scripts and Modules:
- “src/R/Dashboard” – Contains the code for the Shiny dashboard (ui.R, server.R) plus resources (HTML, CSS, downloadable Excel/Word reports), which form the user interface layer.
- “src/R/Modals” – Likely contains modal dialog components (configuration and QA modals).
- “src/R” – Also holds files for risk evaluation (risk_eval.R), report generation (report_html.Rmd, report_word.Rmd), language and label management, and backup files.
- “src/run.R” is used to execute the tool, whereas “src/qa.R” is dedicated to quality control.
- Geospatial Processing:
- The “src/Shapefile_prep” directory includes scripts and configuration files (shapefile_settings.xlsx, geodata_to_shapefiles.R) for standardizing input shapefiles using tools like mapshaper, with geodata and configurations stored for further processing.

##### Main Components
a. Environment & Dependencies:
- R, RStudio, and required R packages (managed via renv).
- External dependencies like web browsers (for the interactive dashboard) and Excel (for data templates).
b. Data Input & Data Sources:
- Shapefiles and Excel files for country data.
- Templates from the “template” folder for multi-lingual data entry.
c. Geospatial Processing Component:
- The “Shapefile_prep” module (script: geodata_to_shapefiles.R) that converts raw geodata formats (SHP/JSON) into standardized shapefiles.
- The output (standardized shapefiles and geocoding Excel file) stored within “src/Data”.
d. Analytics & Processing Layer:
- Risk evaluation engine (risk_eval.R) which uses the prepared data to compute risk levels.
- Data cleaning, translations, and label processing modules (e.g., lang_label_cleanup.R).
e. User Interface - Dashboard:
- Dashboard module (with ui.R and server.R) hosted on a web browser.
- Additional components such as modals (configuration and quality assurance modals) and supplementary assets (CSS, downloadable reports).
f. Reporting & Quality Assurance:
- Reporting components generating HTML and Word reports (report_html.Rmd, report_word.Rmd).
- A dedicated QA module (qa.R) to verify the tool’s outputs.
g. Execution and Control:
- The run scripts (run.R and qa.R) which kick off the overall workflow and quality control processes.

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% Environment & Dependencies Layer
    subgraph "Environment & Dependencies"
        ENV_RENV["renv Directory"]:::env
        ENV_RPROFILE[".Rprofile"]:::env
        ENV_INSTALL["install.R"]:::env
        ENV_PROJ["polio-risk.Rproj"]:::env
        ENV_LOCK["renv.lock"]:::env
    end

    %% Data Input & Sources Layer
    subgraph "Data Input & Sources"
        DATA_FILES["Country Data & Shapefiles (src/Data)"]:::data
        TEMPL_ENG["Template: ENG"]:::data
        TEMPL_FRA["Template: FRA"]:::data
        TEMPL_SPA["Template: SPA"]:::data
    end

    %% Geospatial Processing Layer
    subgraph "Geospatial Processing"
        SHAPE["Shapefile Preparation (src/Shapefile_prep)"]:::geo
        GEO_SCRIPT["geodata_to_shapefiles.R"]:::geo
        GEO_CONFIG["shapefile_settings.xlsx"]:::geo
    end

    %% Analytics & Processing Layer
    subgraph "Analytics & Processing"
        RISK_EVAL["Risk Evaluation (src/R/risk_eval.R)"]:::anal
        DATA_CLEAN["Data Cleaning (src/R/lang_label_cleanup.R)"]:::anal
        LABELS["Labels (src/R/labels.txt)"]:::anal
        TRANS["Translations (src/R/translations.xlsx)"]:::anal
        BACKUP["Backup Files (src/R/backup)"]:::anal
        RISK_CUTOFFS["Risk Cut-Offs (src/R/risk_cut_offs.xlsx)"]:::anal
    end

    %% User Interface & Reporting Layer
    subgraph "User Interface & Reporting"
        DASHBOARD["Dashboard (src/R/Dashboard)"]:::ui
        UI_UI["ui.R"]:::ui
        UI_SERVER["server.R"]:::ui
        MODALS["Modals (src/R/Modals)"]:::ui
        MODAL_CONFIG["config_modal.R"]:::ui
        MODAL_QA["qa_modal.R"]:::ui
        REPORT_HTML["Report HTML (src/R/report_html.Rmd)"]:::ui
        REPORT_WORD["Report Word (src/R/report_word.Rmd)"]:::ui
        QA_MODULE["QA Module (src/qa.R)"]:::ui
        QA_RMD["QA Report (src/R/QA_report.Rmd)"]:::ui
    end

    %% Execution & Control
    EXEC["Execution (src/run.R)"]:::exec

    %% Connections
    %% Environment supports Data Input
    ENV_RENV -->|"provides dependencies"| DATA_FILES

    %% Templates feed data input
    TEMPL_ENG -->|"data entry"| DATA_FILES
    TEMPL_FRA -->|"data entry"| DATA_FILES
    TEMPL_SPA -->|"data entry"| DATA_FILES

    %% Data flows from Data Input to Geospatial Processing
    DATA_FILES -->|"raw data"| SHAPE

    %% Within Geospatial Processing, configuration and processing scripts
    SHAPE --> GEO_SCRIPT
    SHAPE --> GEO_CONFIG

    %% Geospatial output feeds into Analytics
    SHAPE -->|"processed geodata"| RISK_EVAL

    %% Execution triggers the analytics process
    EXEC -->|"starts processing"| RISK_EVAL
    EXEC -->|"initiates QA"| QA_MODULE

    %% Analytics internal flow
    RISK_EVAL -->|"cleans data"| DATA_CLEAN
    DATA_CLEAN -->|"applies labels"| LABELS
    LABELS --> TRANS
    TRANS --> BACKUP
    BACKUP --> RISK_CUTOFFS

    %% Analytics results drive UI components
    RISK_EVAL -->|"visualizes risk"| DASHBOARD
    RISK_EVAL -->|"generates report"| REPORT_HTML
    RISK_EVAL --> REPORT_WORD

    %% Dashboard internal components
    DASHBOARD --> UI_UI
    DASHBOARD --> UI_SERVER

    %% UI Modals for configuration and QA
    DASHBOARD --> MODALS
    MODALS --> MODAL_CONFIG
    MODALS --> MODAL_QA

    %% Reporting quality assurance flow
    QA_MODULE --> QA_RMD

    %% Styling
    classDef env fill:#f4c2c2,stroke:#a83232,stroke-width:2px;
    classDef data fill:#c2d4f4,stroke:#3255a8,stroke-width:2px;
    classDef geo fill:#d4f4c2,stroke:#4a8c32,stroke-width:2px;
    classDef anal fill:#f4e1c2,stroke:#a87c32,stroke-width:2px;
    classDef ui fill:#e1c2f4,stroke:#7c32a8,stroke-width:2px;
    classDef exec fill:#c2f4e1,stroke:#329a78,stroke-width:2px;

    %% Click Events for Environment & Dependencies
    click ENV_RENV "https://github.com/oliversinn/polio-risk/tree/main/renv/"
    click ENV_RPROFILE "https://github.com/oliversinn/polio-risk/blob/main/.Rprofile"
    click ENV_INSTALL "https://github.com/oliversinn/polio-risk/blob/main/install.R"
    click ENV_PROJ "https://github.com/oliversinn/polio-risk/blob/main/polio-risk.Rproj"
    click ENV_LOCK "https://github.com/oliversinn/polio-risk/blob/main/renv.lock"

    %% Click Events for Data Input & Sources
    click DATA_FILES "https://github.com/oliversinn/polio-risk/tree/main/src/Data"
    click TEMPL_ENG "https://github.com/oliversinn/polio-risk/tree/main/template/ENG"
    click TEMPL_FRA "https://github.com/oliversinn/polio-risk/tree/main/template/FRA"
    click TEMPL_SPA "https://github.com/oliversinn/polio-risk/tree/main/template/SPA"

    %% Click Events for Geospatial Processing
    click SHAPE "https://github.com/oliversinn/polio-risk/tree/main/src/Shapefile_prep"
    click GEO_SCRIPT "https://github.com/oliversinn/polio-risk/blob/main/src/Shapefile_prep/geodata_to_shapefiles.R"
    click GEO_CONFIG "https://github.com/oliversinn/polio-risk/blob/main/src/Shapefile_prep/shapefile_settings.xlsx"

    %% Click Events for Analytics & Processing
    click RISK_EVAL "https://github.com/oliversinn/polio-risk/blob/main/src/R/risk_eval.R"
    click DATA_CLEAN "https://github.com/oliversinn/polio-risk/blob/main/src/R/lang_label_cleanup.R"
    click LABELS "https://github.com/oliversinn/polio-risk/blob/main/src/R/labels.txt"
    click TRANS "https://github.com/oliversinn/polio-risk/blob/main/src/R/translations.xlsx"
    click BACKUP "https://github.com/oliversinn/polio-risk/tree/main/src/R/backup"
    click RISK_CUTOFFS "https://github.com/oliversinn/polio-risk/blob/main/src/R/risk_cut_offs.xlsx"

    %% Click Events for User Interface & Reporting
    click DASHBOARD "https://github.com/oliversinn/polio-risk/tree/main/src/R/Dashboard"
    click UI_UI "https://github.com/oliversinn/polio-risk/blob/main/src/R/Dashboard/ui.R"
    click UI_SERVER "https://github.com/oliversinn/polio-risk/blob/main/src/R/Dashboard/server.R"
    click MODALS "https://github.com/oliversinn/polio-risk/tree/main/src/R/Modals"
    click MODAL_CONFIG "https://github.com/oliversinn/polio-risk/blob/main/src/R/Modals/config_modal.R"
    click MODAL_QA "https://github.com/oliversinn/polio-risk/blob/main/src/R/Modals/qa_modal.R"
    click REPORT_HTML "https://github.com/oliversinn/polio-risk/blob/main/src/R/report_html.Rmd"
    click REPORT_WORD "https://github.com/oliversinn/polio-risk/blob/main/src/R/report_word.Rmd"
    click QA_MODULE "https://github.com/oliversinn/polio-risk/blob/main/src/qa.R"
    click QA_RMD "https://github.com/oliversinn/polio-risk/blob/main/src/R/QA_report.Rmd"

    %% Click Event for Execution & Control
    click EXEC "https://github.com/oliversinn/polio-risk/blob/main/src/run.R"
```
