# undp/performance-app-methodology architecture

> Architecture diagram of the GitHub repository undp/performance-app-methodology, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/undp/performance-app-methodology
- Repository: https://github.com/undp/performance-app-methodology

## Overview

##### Project Type and Purpose
- This is a Git-managed documentation site (GitBook) that publishes the UNDP Performance App methodology as a static website.
- The content consists of Markdown files (methodology, SOPs, assets, PDFs), configuration files (SUMMARY.md, README.md), and static assets under `.gitbook/assets`.
- Its purpose is to provide users and stakeholders with a clear, version-controlled methodology for performance indicators, linked to the central Data Warehouse and Performance App.

##### File Structure
- Top-level directories:
– `.gitbook/`: GitBook config and static assets (PDFs, images, spreadsheets).
– `methodology/`: Nested subdirectories for each performance domain (accountability, impact, efficiency, people, values, unscored-indicators).
– `sop/`: Standard operating procedures and technical docs.
- Root files: `README.md`, `SUMMARY.md` (table of contents), `changelog.md`, other markdowns.
- No backend code—this is purely a doc site. No database or server-side code.
- Deployment artifacts are static HTML/CSS/JS generated by GitBook.

##### README for Insights
- Describes high-level rationale, traffic-light system, normalizing methodology, and data sources (the UNDP Data Warehouse and Performance App).

##### Main Components
a. **Developer Environment**
– Local Git clone of this repo
– Authoring in Markdown
b. **CI/CD Pipeline**
– GitHub repository triggers (e.g., GitHub Actions) on push to `main`
– GitBook CLI build step
c. **Static Site Generation**
– Input: Markdown files + `.gitbook/assets`
– Output: HTML/CSS/JS
d. **Hosting Platform**
– GitBook cloud (docs.gitbook.com), or GitHub Pages / Netlify / UNDP SharePoint site
e. **End Users**
– Web browsers (internal staff, external stakeholders)
f. **External Systems**
– UNDP Data Warehouse (data source for actual Performance App)
– Performance App Web Application (links back to methodology for context)

##### Relationships and Data Flows
- Developer → pushes Markdown → CI/CD
- CI/CD → runs GitBook build → produces static site → deploys to Hosting
- End User (browser) → requests static site → views methodology
- Methodology site ↔ static links to Performance App (hosted elsewhere)
- Performance App ↔ Data Warehouse (live data)

##### Architectural Patterns and Principles
- **Static Site Generator (SSG)**: Single responsibility for docs publishing.
- **Version Control**: All content and changes tracked in Git.
- **CI/CD**: Automate build & deploy on each commit.
- **Separation of Concerns**: Docs repo is decoupled from the Performance App application and its Data Warehouse.
- **Content Organization**: Hierarchical, topic-based directory structure aligns with GitBook’s SUMMARY.md.

##### Technologies and Frameworks
- GitBook CLI (SSG)
- GitHub (Version control, possibly Actions for CI/CD)
- Markdown, PDF, XLSX for content
- Hosting: GitBook.com or GitHub Pages or Netlify or UNDP SharePoint
- External: UNDP Data Warehouse, Performance App front-end (likely a React/PowerBI embedded app)

##### Key Details to Capture
- The **GitBook assets folder** containing PDFs and static resources
- The **SUMMARY.md** as the navigation configuration for GitBook
- The **CI/CD trigger** on each commit to the repo
- The **deployment target** (URL or hosting service)
- The **relationship** between the methodology docs and the Performance App that consumes these guidelines

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Developer & CI/CD
    subgraph "Developer & CI/CD"
        LocalDev["Local Developer Environment"]:::dev
        GitRepo["GitHub Repository"]:::dev
        CI["CI/CD Pipeline (GitHub Actions)"]:::dev
        LocalDev -->|git clone| GitRepo
        GitRepo -->|git push to main| CI
    end

    %% Documentation Source
    subgraph "Documentation Source"
        subgraph "Root Documentation"
            README["README.md"]:::doc
            SUMMARY["SUMMARY.md"]:::doc
            CHANGELOG["changelog.md"]:::doc
            DEFINITIONS["definitions.md"]:::doc
            FAQ["faq.md"]:::doc
            DASHBOARDS["list-of-undp-dashboards.md"]:::doc
            ROADMAP["roadmap.md"]:::doc
        end

        subgraph ".gitbook Configuration"
            GITBOOK[".gitbook/"]:::doc
            ASSETS[".gitbook/assets/"]:::doc
        end

        subgraph "Methodology Content"
            ACC["methodology/accountability/"]:::doc
            EFF["methodology/efficiency/"]:::doc
            IMP["methodology/impact/"]:::doc
            PPL["methodology/people/"]:::doc
            VAL["methodology/values/"]:::doc
            UNSCORED["methodology/unscored-indicators/"]:::doc
            subgraph "Global Methodology Pages"
                COOV["methodology/country-office-overview.md"]:::doc
                GUSCORE["methodology/global-undp-score.md"]:::doc
                MPLIST["methodology/master-project-list.md"]:::doc
                OUMAP["methodology/operating-unit-mapping.md"]:::doc
            end
        end

        subgraph "Standard Operating Procedures"
            SDS["sop/data-sources.md"]:::doc
            DSC["sop/digital-standards-compliance.md"]:::doc
            DFM["sop/downloading-full-methodology.md"]:::doc
            FCL["sop/full-changelog.md"]:::doc
            ITG["sop/indicator-template.md"]:::doc
            PBI["sop/powerbi-access.md"]:::doc
            RES["sop/resources.md"]:::doc
            TDO["sop/technical-docs.md"]:::doc
            TCL["sop/testing-checklist.md"]:::doc
        end
    end

    %% Build & Deployment
    subgraph "Build & Deployment"
        Build["GitBook Build (CLI)"]:::build
        GitRepo -->|trigger build| Build
    end

    %% Hosting
    subgraph "Hosting Platform"
        Host["GitBook/GitHub Pages/Netlify/SharePoint"]:::host
        Build -->|deploy static site| Host
    end

    %% End Users
    subgraph "End Users"
        Browser["Web Browser (Staff & Stakeholders)"]:::user
        Browser -->|HTTP GET| Host
    end

    %% External Systems
    subgraph "External Services"
        PerfApp["Performance App Web Application"]:::ext
        DataWH["UNDP Data Warehouse"]:::ext
        PerfApp -->|live data| DataWH
    end

    %% Links between docs and app
    Host -->|links to methodology| PerfApp

    %% Click Events
    click GITBOOK "https://github.com/undp/performance-app-methodology/tree/Main/.gitbook/"
    click ASSETS "https://github.com/undp/performance-app-methodology/tree/Main/.gitbook/assets/"
    click SUMMARY "https://github.com/undp/performance-app-methodology/blob/Main/SUMMARY.md"
    click README "https://github.com/undp/performance-app-methodology/blob/Main/README.md"
    click CHANGELOG "https://github.com/undp/performance-app-methodology/blob/Main/changelog.md"
    click DEFINITIONS "https://github.com/undp/performance-app-methodology/blob/Main/definitions.md"
    click FAQ "https://github.com/undp/performance-app-methodology/blob/Main/faq.md"
    click DASHBOARDS "https://github.com/undp/performance-app-methodology/blob/Main/list-of-undp-dashboards.md"
    click ROADMAP "https://github.com/undp/performance-app-methodology/blob/Main/roadmap.md"
    click ACC "https://github.com/undp/performance-app-methodology/tree/Main/methodology/accountability/"
    click EFF "https://github.com/undp/performance-app-methodology/tree/Main/methodology/efficiency/"
    click IMP "https://github.com/undp/performance-app-methodology/tree/Main/methodology/impact/"
    click PPL "https://github.com/undp/performance-app-methodology/tree/Main/methodology/people/"
    click VAL "https://github.com/undp/performance-app-methodology/tree/Main/methodology/values/"
    click UNSCORED "https://github.com/undp/performance-app-methodology/tree/Main/methodology/unscored-indicators/"
    click COOV "https://github.com/undp/performance-app-methodology/blob/Main/methodology/country-office-overview.md"
    click GUSCORE "https://github.com/undp/performance-app-methodology/blob/Main/methodology/global-undp-score.md"
    click MPLIST "https://github.com/undp/performance-app-methodology/blob/Main/methodology/master-project-list.md"
    click OUMAP "https://github.com/undp/performance-app-methodology/blob/Main/methodology/operating-unit-mapping.md"
    click SDS "https://github.com/undp/performance-app-methodology/blob/Main/sop/data-sources.md"
    click DSC "https://github.com/undp/performance-app-methodology/blob/Main/sop/digital-standards-compliance.md"
    click DFM "https://github.com/undp/performance-app-methodology/blob/Main/sop/downloading-full-methodology.md"
    click FCL "https://github.com/undp/performance-app-methodology/blob/Main/sop/full-changelog.md"
    click ITG "https://github.com/undp/performance-app-methodology/blob/Main/sop/indicator-template.md"
    click PBI "https://github.com/undp/performance-app-methodology/blob/Main/sop/powerbi-access.md"
    click RES "https://github.com/undp/performance-app-methodology/blob/Main/sop/resources.md"
    click TDO "https://github.com/undp/performance-app-methodology/blob/Main/sop/technical-docs.md"
    click TCL "https://github.com/undp/performance-app-methodology/blob/Main/sop/testing-checklist.md"

    %% Styles
    classDef dev fill:#D6E9FE,stroke:#4B8BDA;
    classDef doc fill:#E2FDE2,stroke:#2E8A3E;
    classDef build fill:#FCF4D1,stroke:#E0A800;
    classDef host fill:#FFEFD5,stroke:#FF8C00;
    classDef user fill:#F0F0F0,stroke:#666;
    classDef ext fill:#F3E2F9,stroke:#8A2BE2;
```
