DOCUMENTATION: Add interactive solution dependency graph

[cjdutoit]

closes #24

Summary

Lifts the dependency graph from
LondonFhirService#176
into this repo and re-scans it against this solution. Documentation and CI
only — no production code changes.

The renderer is carried over unchanged apart from branding and the data
global (window.APIPLATFORM_DATA); graph-data.js is written from scratch
for this codebase: 27 components and 84 edges across the SDK, the AspNetCore
companion package, the Infrastructure generator and the external surfaces the
solution actually calls.

What's included

• Documentation/DependencyGraph/index.html — the renderer, carrying two
  views behind one toggle:

  • single copy (default) — every component drawn once with its full
    method surface, all consumers converging on it. Best for who touches
    this?
  • per consumer — dependencies duplicated per caller, each copy showing
    only the method rows that caller uses. Best for what does this one call
    path do?

  Clicking a component header or a single method row traces the full upstream
  and downstream slice and dims everything else; the selection is outlined in
  amber. Search, a utility-broker toggle, and pan/zoom are included. The view
  is reflected in the URL (#single / #duplicated) so links are shareable.

• graph-data.js — all data (window.APIPLATFORM_DATA).

• README.md — how to read the graph, the modelling decisions behind it,
  and the current truths the scan captured.

• .github/workflows/pages.yml — publishes the folder to GitHub Pages on
  pushes to main that touch it.

• .claude/skills/update-dependency-graph/SKILL.md — refreshes the
  snapshot: re-scans the solution, diffs against graph-data.js, and
  re-verifies the rendered graph.

Notable things the scan surfaced

Recorded in the graph README rather than changed here — each is worth a
separate decision:

• ApiPlatformClientFacade is dead code. An internal IApiPlatformClient
  holding the same two sub-clients, but nothing constructs or registers it —
  AddApiPlatformSdkCore registers a hand-built ApiPlatformClient instead.
  It appears on the graph with no inbound flows.
• PdsOrchestrationService injects IApiPlatformTokenBroker and never
  calls it — the access token comes from
  CareIdentityService.GetAccessTokenAsync.
• The three ISL.Providers.PDS.* package references are unused — no
  .cs file mentions Abstractions, FakeFHIR or FHIR; the PDS call is
  hand-rolled over IHttpBroker.
• The storage brokers are registered with TryAdd, so ordering decides
  whether a web host gets the session brokers or the process-wide in-memory
  singletons — AddApiPlatformSdkAspNetCore() has to come before
  AddApiPlatformSdkInMemoryStorage().
• GetAccessTokenAsync returns an empty string rather than throwing when
  both tokens have expired; the orchestration is what turns that into
  UnauthorizedPdsOrchestrationException.
• PDS responses are never deserialised — PdsService returns raw FHIR
  JSON, and the Patient / Address / PatientLookup models are unused.
• JsonBroker.Serialize has no callers.
• ReactApp1.Server and reactapp1.client are empty scaffolding (no source
  files, not in the .slnx), so they are not modelled.

Validation

• Both views render with no console errors: 25 components · 79 flows (single
  copy) and 100 nodes · 413 flows (per consumer); 27 · 84 and 113 · 441 with
  utility brokers on.
• No node-rect or project-box overlaps in either view, with the utility toggle
  both off and on.
• Side-panel flows spot-checked against the source for the orchestration, the
  processing service and a shared broker interface.
• Clearing a selection restores every node attribute byte-identically.

Note on pages.yml

build.yml and prLinter.yml in this repo are generated by
NHSDigital.ApiPlatform.Infrastructure. pages.yml is hand-authored —
the GitHub Pages actions fall outside ADotNet 4.1.0's task model. Regenerating
the other two will not touch it; there is a comment in the file saying so. If
you would rather it were generated, that is a follow-up on
ScriptGenerationService.

Before merge

GitHub Pages needs enabling once under Settings → Pages with the source
set to GitHub Actions, otherwise the deploy job will fail on the first
run after merge.

[Copilot]

Pull request overview

Adds a self-contained, interactive solution dependency graph (HTML renderer + data snapshot + usage docs) and publishes it via GitHub Pages so the architecture can be browsed without building the repo.

Changes:

• Added an interactive SVG-based dependency graph renderer with single-copy and per-consumer (duplicated) views.
• Added a scanned snapshot data model (graph-data.js) plus a README explaining how to interpret and refresh the graph.
• Added a GitHub Pages workflow to publish the graph folder on pushes to main, plus a Claude skill doc for refreshing the snapshot.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
Documentation/DependencyGraph/README.md	Documents how to read the dependency graph and how to refresh it.
Documentation/DependencyGraph/index.html	Self-contained renderer (UI + layout + interactions) that reads window.APIPLATFORM_DATA.
Documentation/DependencyGraph/graph-data.js	Snapshot of components/edges/projects used by the renderer.
.github/workflows/pages.yml	Publishes the dependency graph folder to GitHub Pages on changes.
.claude/skills/update-dependency-graph/SKILL.md	Procedure for rescanning the solution and regenerating graph-data.js.

Suppressed comments (1)

.github/workflows/pages.yml:59

• Same indentation issue in the deploy job: the list item under steps: must be indented, otherwise the workflow won’t parse.

    steps:
    - name: Deploy to GitHub Pages
      id: deployment
      uses: actions/deploy-pages@v4

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.