How undp/performance-app-methodology works
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