Skip to content

CLAUDE.md

Latest commit

 

History

History
352 lines (257 loc) · 12.8 KB

CLAUDE.md

File metadata and controls

352 lines (257 loc) · 12.8 KB
Raw

National Reusable Code Library — Project Brief

What This Is

A static site catalogue for NHS healthcare data code. The site indexes GitHub repositories (public and private) using structured YAML metadata. The goal is to make NHS reusable code discoverable, shareable, and easier to adapt across organisations.

This is a prototype. Prioritise working software over polish.

Creative Latitude

This brief is a starting point, not a contract. The design decisions below represent one reasonable approach based on the inspiration sites studied. If you see a better way to achieve the goals — a cleaner architecture, a more capable stack, a more compelling UI — use it. Don't let prior thinking constrain a better outcome.

Hard constraints (non-negotiable):

  • Python-based development toolchain
  • Deploys free to GitHub Pages via GitHub Actions
  • Open source
  • NHS branding (colour palette and font in the NHS Branding section)
  • Data stored as YAML files in library/ — this is the contract for submissions

Everything else is a suggestion. The tech stack, page structure, build approach, JS libraries, and UI layout are all open to revision if you have a stronger choice. Document any significant departures from this brief in a DECISIONS.md file at the repo root so the human can understand what changed and why.

Inspiration sites to study — take what works, leave what doesn't:

Suggested Tech Stack

These are the starting choices, not mandates. Override with justification in DECISIONS.md.

Layer Suggestion Reason
Static site MkDocs + Material theme Python-native; NHS Data Science already uses it
Catalog rendering Client-side JS + Bootstrap 5 No server needed; follows SolEx pattern
Data storage YAML per entry in library/ Human-readable, PR-reviewable, validatable
Build pipeline MkDocs hook or scripts/build.py YAML → catalog.json at build time
Deployment GitHub Actions → GitHub Pages Free, automated
Submissions GitHub Issue templates No auth required; structured; reviewable

NHS Branding

Use the NHS identity palette throughout. Key colours:

Name Hex
NHS Blue #005EB8
NHS Dark Blue #003087
NHS Bright Blue #0072CE
NHS Light Blue #41B6E6
NHS Aqua Blue #00A9CE
NHS Green #009639
NHS Light Green #78BE20
NHS Orange #ED8B00
NHS Warm Yellow #FFB81C
NHS Purple #330072
NHS Pink #AE2573
NHS Dark Grey #425563
NHS Mid Grey #768692
NHS Pale Grey #E8EDEE

Font: use the NHS standard — Frutiger if available, fallback to Arial then sans-serif.

Tier badge colours (consistent with HSMA Atlas):

  • Baseline — #768692 (mid grey)
  • Bronze — #CD7F32
  • Silver — #9EA8B3
  • Gold — #D4AC0D

Site Structure

/                   Home — hero, featured entries, success stories, stats
/catalog/           Browse all entries — filterable, searchable card grid
/submit/            How to submit — links to GitHub Issue template + guidance
/about/             Project background, the SUL principle, reusability framework
/framework/         Full reusability framework (Baseline → Gold) reference page
/categories/        Full category taxonomy reference page

Home page sections (in order)

  1. Hero — name, tagline, CTA button to /catalog/
  2. Stats bar — total entries, languages, organisations
  3. Featured entries — 3–4 cards marked featured: true
  4. Success stories — entries with success_story: true, shown with outcome text
  5. Recently added — last 6 entries by date_added
  6. Tier breakdown — visual summary of how many entries at each tier

Data Model

Each entry lives at library/<slug>/metadata.yaml. See docs/reference/data_model.md for the full field reference and validation rules.

Seed entries for testing: library/nhs-number-validator/, library/waiting-list-des/, library/ae-daily-extract/. These cover Gold, Silver, and Baseline tiers respectively.

Build Pipeline

YAML → JSON

A Python script (or MkDocs hook) reads every library/*/metadata.yaml, validates it, and writes docs/js/catalog.json. The catalog page loads this JSON client-side and renders cards.

library/*/metadata.yaml  →  scripts/build_catalog.py  →  docs/js/catalog.json

The build script should also:

  • Reject invalid entries and print clear errors (so CI catches bad submissions)
  • Compute date_added defaults if missing
  • Sort entries by date_added descending

Validation

A separate scripts/validate.py (or the same script with a --check flag) validates all YAML files against the schema. Run this in CI on every PR that touches library/.

GitHub Infrastructure

Deployment workflow (.github/workflows/deploy.yml)

Trigger: push to main.

Steps:

  1. uv sync
  2. Run the build/validation script
  3. uv run mkdocs build
  4. Deploy site/ to gh-pages branch using peaceiris/actions-gh-pages

PR validation workflow (.github/workflows/validate.yml)

Trigger: PRs that change files under library/.

Steps:

  1. uv sync
  2. Run scripts/validate.py — fail the check if any entry is invalid

Submission Issue template (.github/ISSUE_TEMPLATE/submit_entry.yml)

See the seed template at .github/ISSUE_TEMPLATE/submit_entry.yml.

Catalog Page (UX)

Model this closely on Solutions Exchange. Key requirements:

  • Card grid — 3 columns on desktop, 1 on mobile (Bootstrap 5 grid)
  • Each card shows: title, organisation, description (truncated), language badges, platform badges, reusability tier badge, category tag
  • Filters (sidebar or top bar):
    • Reusability tier (checkboxes: Baseline / Bronze / Silver / Gold)
    • Category (dropdown or checkboxes)
    • Language (multi-select)
    • Platform (multi-select)
    • Visibility (public / private / all)
  • Search — client-side text search over title + description + tags (use Fuse.js or plain substring matching — keep it simple)
  • Sort — newest first by default; option to sort by title or tier
  • Clicking a card opens the entry detail (a separate MkDocs page or a modal)

Entry Detail Page

Each entry gets a generated MkDocs page at docs/catalog/<slug>/index.md (generated by the build script from the YAML). It should show:

  • Title, organisation, description
  • Reusability tier badge + rationale text (if provided)
  • SUL principle compliance table (Structural / Utility / Logic — tick/cross)
  • Category + project type
  • Language + platform badges
  • Links: repo, documentation, package registry (if applicable)
  • Contact info
  • Atlas cross-listing notice (if atlas_listed: true)
  • Date added / last updated

Atlas Cross-Listing

HSMA Atlas (atlas.hsma.co.uk) uses Quarto .qmd files for entries. The atlas_listed and atlas_url fields in our metadata allow us to:

  1. Show a badge on the entry card/detail: "Also listed on HSMA Atlas"
  2. In future: provide a script that generates a .qmd file from our YAML that can be submitted as a PR to the Atlas repo

For the prototype, just implement the badge display. The export script can come later.

Python Conventions

Follow the project's global standards (see global CLAUDE.md):

  • uv for environment management
  • ruff for lint + format
  • Full type hints on all functions
  • pydantic for YAML schema validation
  • pathlib.Path over string paths
  • loguru for logging
  • British English in all user-facing text and documentation

Running Locally (Demo Guide)

Once the site is built, anyone can preview it with:

uv sync
uv run python scripts/build_catalog.py   # generate catalog.json + entry pages
uv run mkdocs serve                       # starts at http://localhost:8000

The demo path to walk through:

  1. Home page — hero, stats bar, featured entries, success stories
  2. Catalog (/catalog/) — filter by tier, category, language; test search
  3. Entry detail — click any card; check tier badge, SUL table, links
  4. Submit (/submit/) — review the submission guidance and Issue template link
  5. Framework (/framework/) — check Baseline → Gold reference renders correctly

For a quick smoke test with no browser, confirm uv run mkdocs build exits 0.

Deployment to GitHub Pages

One-time setup (done by the human, not by CI):

  1. Create a new GitHub repository (public, empty)
  2. Push this repo: git remote add origin <url> && git push -u origin main
  3. In the repo Settings → Pages → Source: set to Deploy from a branch, branch gh-pages, root /
  4. The first push to main triggers the Actions workflow and deploys automatically

After that, every push to main redeploys. The live URL will be https://<org>.github.io/<repo-name>/.

The GitHub Actions deploy workflow lives at .github/workflows/deploy.yml. It should:

  1. uv sync
  2. Run the build/validation scripts
  3. uv run mkdocs build
  4. Push site/ to the gh-pages branch (use peaceiris/actions-gh-pages@v3 or the newer actions/deploy-pages — your choice)

Continuing Development (Handoff Guide)

At the end of your build, create a NEXT_STEPS.md file in the repo root. This file is for less advanced models or human contributors to continue development after you are done.

NEXT_STEPS.md must contain:

Format for each suggested feature

### [Priority: High/Medium/Low] Feature name

**What:** One sentence describing what it does.
**Why:** One sentence on the value it adds.
**Where to start:** The specific file(s) to open first.
**Scope:** Rough size — Small (< 2hrs), Medium (half day), Large (full day+).
**Constraints / gotchas:** Any non-obvious things to know before starting.

Required sections in NEXT_STEPS.md

  1. Quick wins (Small scope) — 4–6 low-effort improvements that add visible value
  2. Core features (Medium scope) — 4–6 features that extend the prototype meaningfully
  3. Advanced features (Large scope) — 3–4 bigger ideas for when the prototype is stable
  4. Atlas collaboration — specific tasks for deepening the HSMA Atlas integration
  5. Operational — maintenance, monitoring, and community-building tasks

Be honest about what you did not build or cut corners on. Flag it in a Known gaps section at the top of NEXT_STEPS.md so the next contributor knows what to fix before adding new features.

Task Order for Fable

The phases below are a suggested sequence. Reorder or merge them if your chosen architecture makes a different order more natural. The only firm rule: get something that builds and deploys before building features on top of it.

Complete each phase before starting the next.

Phase 1 — Working skeleton (get something that builds and deploys)

  • pyproject.toml with all dependencies
  • Site framework configured (MkDocs or your chosen alternative) with NHS colours
  • A placeholder home page that renders
  • .github/workflows/deploy.yml — builds and deploys to Pages
  • .github/workflows/validate.yml — validates entries on PRs to library/
  • Gate: uv run mkdocs build (or equivalent) exits 0 before proceeding

Phase 2 — Data model & validation

  • Pydantic models for entry metadata covering the full schema in docs/reference/data_model.md
  • Validation script that checks all library/*/metadata.yaml files
  • Gate: all 3 seed entries pass validation before proceeding

Phase 3 — Build pipeline

  • Script/hook: YAML → catalog.json (and any generated entry pages)
  • Wired into the deploy workflow
  • Gate: catalog.json is present and contains the 3 seed entries after build

Phase 4 — Catalog page

  • Card grid with filter and search
  • NHS-styled tier badges, language badges, platform tags
  • Responsive layout (mobile + desktop)
  • Gate: filtering and search work correctly against the seed entries

Phase 5 — Home page

  • Hero with NHS branding and CTA
  • Stats bar, featured entries, success stories, recently added, tier breakdown

Phase 6 — Supporting pages

  • /submit/ — submission guidance
  • /about/ — SUL principle, project background
  • /framework/ and /categories/ — rendered from the reference docs

Phase 7 — Content and polish

  • 8–12 synthetic seed entries covering all 6 categories and all 4 tiers
  • Mobile layout check
  • Atlas cross-listing badge on detail pages
  • README.md with setup instructions

Phase 8 — Handoff

  • DECISIONS.md documenting any departures from this brief
  • NEXT_STEPS.md following the format in the Continuing Development section above