GMD Human Review App — How It Works

A plain-language guide for whoever picks this up next. No R, no jargon. By the end you should know what each piece does, who can do what, and how to push a change to the live app.

1. The big picture

The GMD team writes canonical variable rules — the official guidance for how household survey variables should be harmonized across countries. A computer (an AI-assisted draft) proposes how a new survey's variables map to those rules. A human needs to look at each proposal and either accept it, send it back for revision, or block it.

The Human Review App is the website where humans do that. It's a small Shiny web app running on the World Bank's Posit Connect server. Reviewers open it in a browser, see a queue of items to review, and click through to approve, request changes, or reopen previously approved items.

Figure 1. Where the app fits: it sits between the drafts and the canonical rules.

2. The four moving parts

Think of the system as four boxes that talk to each other. You can keep the whole thing running just by understanding what each one does.

Figure 2. The four boxes and the path data takes when a reviewer opens the app.

3. What happens when someone reviews a variable

The app enforces a small state machine. A variable moves through these states; only certain roles can move it forward.

Figure 3. The lifecycle of a single review item, with the role allowed for each transition.

Plain-English version of the same flow:

1. A draft appears in the queue.
2. A reviewer reads it and clicks Submit when they think it's ready.
3. An approver either clicks Approve (it goes to the canonical output) or Request revision (it goes back).
4. If it's been approved, only an administrator can reopen it.
5. If it was sent back for revision, a reviewer can submit again (the review round counter increments).

4. Who is allowed to do what

There are exactly three roles, defined in review-app/config/roles.yml. Each person is mapped to exactly one role (their username must match what Connect returns in session$user).

Current map: 1 administrator (acastanedaa), 3 approvers (clakner, dmahler, mnguyen3), 15 reviewers. Edit review-app/config/roles.yml, commit, push, and redeploy to change it. There is no in-app way to edit roles — that's a deliberate safety choice.

5. How to push a change to the live app

This is the most important section for whoever takes over. Two facts that often surprise people:

1. The "Deploy" button in the Connect UI does NOT pull new code from GitHub. It just re-runs the bundle that's already uploaded. To get new code live, you must push a fresh bundle from your machine.
2. Pushing to main does NOT auto-deploy. GitHub is the source of truth, but Connect doesn't watch it. You still have to run the deploy command below.

The deploy command (run from the repo root)

Every code or role change goes out with this recipe. It works on macOS or Linux, from any terminal that has R installed.

# 1. Make sure your working copy is clean and on main
cd /path/to/GMD-canonical-schema
git checkout main
git pull

# 2. Make your changes (edit code, edit roles.yml, etc.)

# 3. Commit and push
git add .
git commit -m "describe what you changed"
git push origin main

# 4. Ship to Connect (this is the magic command)
RENV_CONFIG_AUTOLOADER_ENABLED=FALSE Rscript -e '
rsconnect::deployApp(
  appDir      = "review-app",
  appFiles    = c("DESCRIPTION", "NAMESPACE", "app.R", "renv.lock",
                  "R/", "inst/", "config/"),
  appName     = "review-app",
  appTitle    = "review-app",
  appId       = "88dcd5b3-91b0-47fd-97b6-b1e420c683f2",
  account     = "acastanedaa",
  server      = "wbconnect",
  lint        = FALSE,
  dependencyResolution = "library"
)'

What those flags mean

• RENV_CONFIG_AUTOLOADER_ENABLED=FALSE — skips the project-level renv autoloader so the rsconnect package is found in your user library.
• appId — the existing content item's GUID on Connect. Re-using this updates the existing item in place rather than creating a new one.
• server = "wbconnect" — the nickname of the Connect server, registered in your ~/.Rprofile or .Renviron with an API key.
• appFiles — exact list of files to include in the bundle. Keep this in sync with the project structure.
• dependencyResolution = "library" — tells rsconnect to trust the existing renv.lock instead of re-checking it against the local R library.

Pre-requisites (one-time setup)

Before any of the above works, the machine you're deploying from needs three things in ~/.Renviron:

CONNECT_SERVER=https://datanalytics-int.worldbank.org
CONNECT_API_KEY=your-personal-key-here

The API key comes from the Connect UI (your name → API Keys → Add). The first deploy also requires the rsconnect R package, installed once with:

Rscript -e 'install.packages("rsconnect")'

On macOS this writes to ~/Library/R/<arch>/<R-version>/library and works for every subsequent deploy.

6. Common tasks & recipes

Add or remove a reviewer

1. Edit review-app/config/roles.yml — add or remove the - identity: entry.
2. Commit, push, redeploy (see section 5).

Promote someone from reviewer to approver

Same as above — change their role: line from reviewer to approver, commit, push, redeploy.

Change a code bug or feature

1. Edit the relevant R/<file>.R.
2. Commit, push, redeploy.

Rotate the GitHub App private key (compromise / annual rotation)

1. Generate a new private key in GitHub → your GitHub App → Private keys → Generate.
2. Save the new .pem to a secure location.
3. Set the new key on the content item. From the repo root:

   Rscript -e '
   suppressMessages(library(httr))
   pem <- paste(readLines("/secure/path/new-key.pem"), collapse = "\n")
   httr::PUT(paste0(Sys.getenv("CONNECT_SERVER"),
                    "/__api__/v1/content/88dcd5b3-91b0-47fd-97b6-b1e420c683f2/environment"),
     httr::add_headers(Authorization = paste0("Key ", Sys.getenv("CONNECT_API_KEY")),
                       "Content-Type" = "application/json"),
     body = jsonlite::toJSON(list(list(name="GITHUB_APP_PRIVATE_KEY", value=pem)),
                             auto_unbox=TRUE))
   '

4. The next deploy picks up the new secret automatically (env vars are read at app startup).

Add a new env var (e.g. another GitHub App)

Same PUT shape as above; send an array of {name, value} objects.

Roll back a bad deploy

1. In Connect, find the previous content version (or previous bundle ID) and redeploy from the UI.
2. OR: git revert the offending commit, push, and run the deploy command again.

7. Troubleshooting quick-reference

8. Glossary

Last updated: August 2026. Generated as part of the Connect deployment fix (commit cddb0d5). If something has changed since then, update this doc as part of the change.