Program Health Diagnostic

Last updated: 2026-06-29

Program Health Diagnostic is an evidence-based assessment application for critical programs. It helps sponsors, program leaders, delivery teams, and advisors collect structured facts, save and resume diagnostic responses, and build toward transparent health findings.

Repository Layout

backend/   FastAPI API, SQLite models, migrations, auth, questions, and tests
frontend/  React/Vite TypeScript application shell and assessment workflow
data/      Versioned question sets and local/runtime user artifact locations
docs/      Product design, backlog, and operating documentation
scripts/   Local helper and guardrail scripts
wip/       Working notes

Architecture Pointers

• Product design: docs/pgmhlth-diagnostic-design.md
• Product backlog: docs/pgmhlth-diagnostic-product-backlog.md
• Diagnostic engine: docs/diagnostic-engine.md
• LLM guidance: docs/llm-guidance.md
• Reporting: docs/reporting.md
• Admin configuration: docs/admin-configuration.md
• Local development: docs/local-development.md
• Deployment and packaging: docs/deployment.md
• Operations: docs/operations.md
• Agent guidance: AGENT.md

Local Development

Backend:

Push-Location backend
python -m pip install -e .[dev]
python -m uvicorn app.main:app --reload
Pop-Location

Frontend:

Push-Location frontend
npm install
npm run dev
Pop-Location

The default backend security mode is none, which returns a local development user. Use poc_users with an encrypted user artifact for demo/cloud POC flows.

For local AI guidance, install Ollama and pull the configured model, or set PGMHLTH_LLM_PROVIDER=disabled to run without LLM features.

Packaged local mode:

docker compose up --build

The packaged image serves the React production build through FastAPI on http://localhost:8080 with SQLite persisted in a named Docker volume.