Skip to content

HealthArchive Documentation

This documentation portal covers the HealthArchive app monorepo and links to the separate datasets documentation.

Shared VPS inventory, ingress ownership, canonical public hosts, and cross-project operations state live in /home/jer/repos/vps/platform-ops. Use /home/jer/repos/vps/platform-ops/docs/standards/PLAT-009-shared-vps-documentation-boundary.md as the default rule for what belongs in this repo versus shared ops documentation.

Quick Start by Role

Choose your path:

Key Resources

Need Documentation
Architecture overview Architecture
Production deployment Production Runbook
Local development setup Dev Setup
Incident response Incident Response
Search API API Documentation
Monitoring setup Monitoring

Documentation Structure

This docs portal is built from docs/ in the app monorepo. Frontend-specific docs remain canonical under frontend/docs/ and are surfaced here through the docs/frontend/ bridge; datasets docs remain canonical in the separate datasets repo:

  • Frontend bridge: frontend/README.md
  • Datasets pointers: datasets-external/README.md

Shared VPS facts that are not specific to the backend are canonical in:

  • /home/jer/repos/vps/platform-ops
  • /home/jer/repos/vps/platform-ops/docs/standards/PLAT-009-shared-vps-documentation-boundary.md
  1. Project docs portal (monorepo + datasets navigation)
  2. project.md
  3. Architecture & implementation (how the code works)
  4. architecture.md
  5. Documentation guidelines (how docs stay sane)
  6. documentation-guidelines.md
  7. documentation-process-audit.md (audit of doc processes; 2026-01-09)
  8. decisions/README.md (decision records for high-stakes choices)
  9. Local development / live testing (how to run it locally)
  10. development/live-testing.md
  11. development/dev-environment-setup.md (local setup + local vs VPS guidance)
  12. development/testing-guidelines.md (backend test expectations)
  13. Deployment (how to run it on a server)
  14. deployment/production-single-vps.md (current production runbook)
  15. deployment/systemd/README.md (systemd units: annual scheduler, crawl monitoring + auto-recovery, baseline drift, replay reconcile + smoke tests, change tracking, annual search verify, coverage guardrails, cleanup automation, worker priority)
  16. deployment/replay-service-pywb.md (pywb replay service for full-fidelity browsing)
  17. deployment/search-rollout.md (enable v2 search + rollback)
  18. deployment/pages-table-rollout.md (pages table backfill + browse fast path)
  19. deployment/hosting-and-live-server-to-dos.md (historical hosting notes + optional future staging ideas)
  20. deployment/environments-and-configuration.md (frontend/backend env vars + host matrix)
  21. deployment/production-rollout-checklist.md (generic production checklist)
  22. deployment/staging-rollout-checklist.md (optional future staging)
  23. Operations (how to keep it healthy)
  24. operations/README.md (index of ops docs)
  25. Roadmaps and implementation plans
  26. planning/README.md
  27. roadmap-process.md (short pointer)

Notes

  • No secrets live in this repo. Any token/password values shown in docs must be placeholders.
  • The archive_tool crawler has its own internal documentation at src/archive_tool/docs/documentation.md.