P004 SafetyGraphics Renderer Modernization
Goal
Modernize the legacy Safety Explorer Suite JavaScript renderers so they can become maintained SafetyGraphics tools with cleaner dependencies, stronger tests, and a shared design language for both interactive monitoring graphics and future static safety displays.
The current suite documentation describes nine custom interactive graphics, maintained as separate repositories, plus supporting JavaScript/R frameworks. The legacy renderers were built on d3 v3 and webcharts; this project will remove the webcharts dependency and move toward independent modern JavaScript renderers, likely using Chart.js where it fits the display model.
Coordination repository
The shared agent framework for this modernization program lives at https://github.com/obot-claw/safety-agent. It contains the GxP-oriented workflow rules, requirements-harvesting process, test framework guidance, and reusable agent skills for renderer migrations.
Source inventory
Initial forks were created under obot-claw as staging repositories before eventual transfer or replacement under SafetyGraphics.
| Area | Upstream | Staging fork | Role |
|---|---|---|---|
| AE Explorer | https://github.com/RhoInc/aeexplorer | fork | Adverse event incidence explorer |
| AE Timelines | https://github.com/RhoInc/ae-timelines | fork | Participant AE timeline display |
| Safety Outlier Explorer | https://github.com/RhoInc/safety-outlier-explorer | fork | Longitudinal participant outlier review |
| Paneled Outlier Explorer | https://github.com/RhoInc/paneled-outlier-explorer | fork | Multi-measure participant outlier panels |
| Safety Results Over Time | https://github.com/RhoInc/safety-results-over-time | fork | Population trends over visits/time |
| Safety Histogram | https://github.com/RhoInc/safety-histogram | fork | Distribution review for labs/vitals/other safety measures |
| Safety Shift Plot | https://github.com/RhoInc/safety-shift-plot | fork | Baseline-to-postbaseline shift review |
| Safety Delta Delta | https://github.com/RhoInc/safety-delta-delta | fork | Change-over-time multi-measure review |
| Web Codebook | https://github.com/RhoInc/web-codebook | fork | Interactive variable-level data summary |
| Safety Explorer Suite | https://github.com/RhoInc/safety-explorer-suite | fork | Multi-renderer suite shell/framework |
Hep Explorer is already under SafetyGraphics at https://github.com/safetyGraphics/hep-explorer and should be handled separately from the RhoInc fork migration.
Renderer example deployments
GitHub Pages deployments are available for each staging fork. Baseline examples preserve the legacy renderer behavior for comparison. Nextgen examples are early Chart.js spikes used to test display direction before full requirements-driven migrations.
| Renderer | Baseline example(s) | Nextgen spike | Spike PR | Nextgen status |
|---|---|---|---|---|
| AE Explorer | baseline | nextgen | PR #1 | Expanded Chart.js spike with summary mode, search, prevalence filter, treatment grouping, tooltip/listing path. |
| AE Timelines | baseline | nextgen | PR #1 | Expanded Chart.js spike with seriousness, severity, subject, treatment, and sort controls. |
| Safety Outlier Explorer | baseline | nextgen | PR #1 | Expanded Chart.js spike with measure/filter/x-axis controls, participant count, traces, and listing path. |
| Paneled Outlier Explorer | baseline | nextgen | PR #1 | Expanded Chart.js spike with x-axis, normal-range, show-inliers controls, inlier counts, and measure panels. |
| Safety Results Over Time | baseline | nextgen | PR #1 | Expanded Chart.js spike with measure/filter/y-axis controls, participant count, and listing path. |
| Safety Histogram | baseline/nextgen demo | nextgen | PR #1 | Active requirements-driven Chart.js spike. |
| Safety Shift Plot | baseline | nextgen | PR #1 | Expanded Chart.js spike with measure, baseline/comparison, treatment controls, participant count, tooltips, and point listing. |
| Safety Delta Delta | baseline 0 / baseline 1 | nextgen | PR #1 | Expanded Chart.js spike with baseline/comparison, x/y measure, treatment controls, participant count, and point listing. |
| Web Codebook | default baseline / explorer baseline | nextgen | PR #1 | Expanded Chart.js spike with codebook/listing/chart/settings tabs and hide-column controls. |
| Safety Explorer Suite | baseline | Not started | — | Suite-level integration shell after renderer spikes mature. |
Modernization principles
- Keep the clinical display contract stable before changing internals.
- Separate renderer data preparation from chart rendering.
- Prefer explicit schemas for data mappings and settings.
- Replace
webchartsconventions with renderer-local state, lifecycle, and event handling. - Keep interactive and static chart implementations aligned around the same display definitions.
- Add deterministic tests before major rendering rewrites.
- Ship migration in small PRs: dependency cleanup, architecture seams, renderer rewrite, then static/interactive alignment.
Proposed phases
Phase 0: Inventory and planning
- Fork repositories under
obot-claw. - Confirm repository status, package managers, build tools, test coverage, and current examples.
- Identify common renderer patterns across the suite.
- Pick a first package for the modernization spike.
Phase 1: Baseline maintenance pass
- Update repository metadata from RhoInc to staging/SafetyGraphics context.
- Confirm current build/test commands.
- Add current-state CI where missing.
- Document unsupported or archived paths.
- Capture screenshots or example outputs as regression baselines where browser tooling allows.
Phase 2: Shared renderer architecture
Define a minimal renderer lifecycle that can replace Webcharts usage consistently:
init(data)setData(data)setSettings(settings)render()resize()destroy()- event hooks for filter/group/selection/listing updates
Shared modules should cover:
- data validation
- settings validation
- controls/filter state
- accessibility defaults
- browser example harness
- visual regression hooks
Phase 3: First Chart.js renderer spike
Start with Safety Histogram because it is a focused distribution display, has clear data requirements, and exposes the main migration problems without the full complexity of AE tables or linked timelines.
Deep dive: Safety Histogram implementation plan
Phase 4: Suite-wide migration
Apply the proven pattern renderer by renderer:
- Safety Histogram
- Safety Results Over Time
- Safety Shift Plot
- Safety Delta Delta
- Safety Outlier Explorer
- Paneled Outlier Explorer
- AE Timelines
- AE Explorer
- Web Codebook / suite shell as needed
- Hep Explorer coordination with the existing SafetyGraphics repo
Phase 5: Static + interactive alignment
After the interactive renderer architecture is stable, define static chart equivalents for FDA-style reports using the same display contracts where possible. The target is a paired workflow: static submission-style graphics plus interactive monitoring graphics that share data mappings and display intent.
Interview decisions
These decisions are being captured through the Telegram interview workflow and mirrored in the safety-agent interview log at https://github.com/obot-claw/safety-agent/blob/main/interviews/p004-open-questions.md.
| Topic | Decision | Status |
|---|---|---|
| Repository structure | Keep the current fork-per-renderer structure for now; revisit monorepo consolidation after the Safety Histogram spike clarifies shared tooling and release coupling. | Decided |
| Chart.js scope | Use Chart.js as the preferred reference implementation pattern, aligned with gsm.viz, but allow custom SVG/Canvas when justified by renderer requirements. |
Decided |
| Qualification-ready testing | Use the safety-agent implementation-framework spike to define a traceable standard linking wiki requirements to unit, integration, browser, visual-regression, accessibility, and review-evidence checks. |
Decided |
| Legacy API compatibility | Breaking changes are acceptable. Design clean nextgen APIs and release as new major versions or possibly new packages; do not preserve legacy APIs or wrappers by default. | Decided |
| Static chart API boundary | Keep static chart APIs in R-side packages such as gsm.safety or safetyCharts; nextgen renderer repos stay focused on interactive JavaScript renderers. gsm.safety continues orchestrating htmlwidget rendering for interactive outputs. |
Decided |
Open questions
No project-level interview questions remain open. New questions should be added as the Safety Histogram implementation spike exposes concrete design decisions.
Full migration tracker
Full migration is now tracked in safety-agent issue #3: https://github.com/obot-claw/safety-agent/issues/3.
The working definition of done for each renderer is: requirements harvested from the upstream wiki, baseline comparison available, nextgen implementation covering required controls/interactions/listings/exports/error states, browser-test evidence, and a reviewable demo page.
Immediate next step
Continue the Safety Histogram nextgen spike through PR review, then apply the same requirements-driven migration flow to the next renderer using the deployed baseline examples above as regression targets.