> For the complete documentation index, see [llms.txt](https://docs.wellcomecollection.org/request-for-comments-rfcs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.wellcomecollection.org/request-for-comments-rfcs/086-item-viewer-refactor/15-risks-and-success.md).

# Risks & Success Metrics

[← Back to Index](/request-for-comments-rfcs/086-item-viewer-refactor.md)

## Risk Mitigation

### Performance Concerns

**Risk:** Adding more data to context could cause unnecessary re-renders across all consuming components.

**Likelihood:** Low\
**Impact:** Medium

**Mitigation:**

* Use `useMemo` for all derived calculations in context provider
* Test render performance with React DevTools Profiler before and after
* Consider splitting context if it grows too large:
  * `ItemViewerDataContext` (work, manifest, query, derived data)
  * `ItemViewerUIContext` (sidebar, zoom, grid states)
* Monitor bundle size - ensure no significant increase
* Profile with large manifests (100+ canvases)

**Detection:**

* React DevTools shows excessive re-renders
* Lighthouse performance scores decrease
* User reports of lag or slowness

***

### Breaking Changes

**Risk:** Components might depend on local state in ways not immediately obvious. Subtle behaviour changes could occur.

**Likelihood:** Low (with test-first approach)\
**Impact:** High

**Mitigation:**

* Test-first approach catches regressions immediately
* Feature flag allows instant rollback (disable toggle)
* Keep PR size manageable - merge phases separately if needed
* Side-by-side comparison testing (flag ON vs OFF)
* Comprehensive manual testing checklist
* Monitor Sentry for errors while toggle is public

**Detection:**

* Automated tests fail
* Manual testing reveals differences
* Sentry error spike
* User reports of broken functionality

**Rollback:** Disable toggle or revert default, investigate, fix in development, re-enable.

***

### Normalisation Risk

**Risk:** When normalising variant implementations (e.g., `currentCanvas` calculated differently in `ViewerTopBar` vs `ZoomedImage`), the chosen canonical version might not handle all edge cases that the variants handled.

**Likelihood:** Low (with characterisation tests)\
**Impact:** Medium

**Mitigation:**

* Write characterisation tests BEFORE refactoring
* Test all edge cases from all variants
* Document why canonical version was chosen
* Review each variant's fallback behaviour
* Side-by-side comparison testing

**Detection:**

* Tests fail during refactoring
* Manual testing reveals edge case failures
* Unexpected undefined/null values

**Rollback:** Fix canonical implementation to handle all edge cases, or disable toggle.

***

### Type Safety Issues

**Risk:** TypeScript type errors during refactoring, especially with complex IIIF types.

**Likelihood:** Medium\
**Impact:** Low (caught at compile time)

**Mitigation:**

* Update types first before implementation
* Use TypeScript strict mode
* Fix all type errors before testing
* Properly type all mocks and test fixtures
* Use IDE type checking during development
* Run `yarn tsc` frequently during development

**Detection:**

* TypeScript compiler errors
* IDE showing type errors
* CI/CD build failures

**Resolution:** Fix type errors before proceeding. Don't use `any` or `@ts-ignore` to bypass.

***

### Normalisation Risks

**Risk:** When normalising variant implementations (e.g., `currentCanvas` calculated differently in ViewerTopBar vs ZoomedImage), the chosen canonical version might not handle all edge cases that the variants handled.

**Likelihood:** Low (with comprehensive tests)\
**Impact:** Medium

**Mitigation:**

* Document all current implementations before refactoring (phase 1.0)
* Test all edge cases from all variants
* Check fallback behaviour (`|| ''` might be needed in some cases, not others)
* Verify with null, undefined, and empty cases
* Compare behaviour with toggle OFF (legacy) vs ON (refactored)

**Detection:**

* Automated tests catch edge case failures
* Manual testing reveals UI differences
* Images don't load correctly
* Zoom doesn't work in specific scenarios

**Resolution:** Adjust canonical implementation to handle all edge cases, or add component-specific logic where genuinely needed.

***

### Feature Flag Debt

**Risk:** Feature flag left in codebase permanently, creating permanent branching logic.

**Likelihood:** Medium (without discipline)\
**Impact:** Medium

**Mitigation:**

* Set calendar reminder for cleanup (2 weeks after defaulting to ON)
* Include cleanup phase in original plan (Phase 5)
* Document cleanup steps clearly
* Make cleanup PR part of the original epic/project
* Don't consider project "done" until cleanup is merged

**Detection:**

* Feature flag still present months later
* `.legacy.tsx` and `.refactored.tsx` files still in codebase
* Wrapper logic still checking feature flag

**Resolution:** Follow Phase 5 cleanup steps. Remove legacy code, rename refactored code, delete flag.

***

## Success Metrics

### Code Quality Metrics

**Target:** Improvement across all metrics

* **Code reduction:** 150-200 lines removed across components
  * ViewerTopBar: \~65 lines (download logic)
  * IIIFViewer: \~20 lines (calculation logic)
  * ZoomedImage: \~10 lines
  * Other components: \~55-105 lines combined
* **DRY improvement:** Zero duplication of:
  * `currentCanvas` calculation (was in 4 files)
  * `queryParamToArrayIndex` calls (was in 3 files)
  * Download options logic (was only in `ViewerTopBar`, now reusable)
* **Cyclomatic complexity:** Reduced by \~15-20 points
  * `ViewerTopBar` complexity reduced significantly
  * `IIIFViewer` complexity reduced
* **Test coverage:** Increased to >80% for IIIF Viewer components
  * ItemViewerContext: 100% coverage
  * useDownloadOptions: 100% coverage
  * Component integration: >80% coverage

### Maintainability Metrics

**Target:** Easier to understand and modify

* **Single source of truth:** All derived values calculated once, in context
* **Clear naming:** All booleans follow `is/has/can/should` pattern
* **Separation of concerns:** Business logic in context/hooks, presentation in components
* **Reusability:** Download logic hook can be used anywhere
* **Type safety:** All mocks and context values properly typed

### Performance Metrics

**Target:** No regression (same or better performance)

* **Bundle size:** No increase >2KB gzipped
* **Render time:** No increase (verify with React Profiler)
* **Lighthouse score:** Maintain 90+ performance score
* **First Contentful Paint:** Maintain <1.5s
* **Time to Interactive:** Maintain <3s

**How to measure:**

* Before refactoring: Profile with React DevTools, record Lighthouse scores
* After refactoring: Profile again, compare
* Monitor in production with Real User Monitoring (RUM)

### Developer Experience Metrics

**Target:** Easier to work with

* **Onboarding time:** New developers understand viewer code faster
* **Bug fix time:** Easier to locate and fix issues
* **Feature development time:** Easier to add new features
* **Code review time:** PRs easier to review (less mental gymnastics)

**Qualitative feedback:**

* Team survey: "Is the refactored code easier to understand?"
* Code review comments: Fewer questions about "what does this do?"
* Bug reports: Fewer viewer-related bugs after refactor

***

## Success Criteria

The refactoring is successful if:

1. All automated tests pass when toggle is enabled
2. Performance metrics unchanged or improved
3. Error rate in production unchanged
4. Code is more maintainable (team consensus)
5. 150+ lines of code removed
6. Zero duplication of derived calculations
7. Feature flag successfully removed (cleanup complete)
8. Team agrees code is easier to understand

The refactoring has failed if:

1. Tests reveal regressions we can't fix
2. Performance degrades significantly
3. Error rate spikes in production
4. Must revert to legacy implementation
5. Team finds new code harder to understand
6. User-facing bugs introduced

***

## Next Steps

After successfully completing this refactoring:

1. Monitor production metrics for 1-2 weeks with toggle enabled
2. Review team feedback on code maintainability
3. If all success criteria met, proceed to [Phase 5: Cleanup](https://github.com/wellcomecollection/docs/blob/main/rfcs/086-item-viewer-refactor/12-phase-5-cleanup.md)
4. Consider [Future Improvements](/request-for-comments-rfcs/086-item-viewer-refactor/16-future-improvements.md) like component splitting

For different viewer modes:

```typescript
type ViewerMode = 
  | { type: 'images'; work: ImageWork }
  | { type: 'archive'; work: ArchiveWork; archiveTree: ArchiveTree }
  | { type: 'restricted'; work: RestrictedWork; authStatus: AuthStatus };
```

**Benefit:** Type-safe mode handling

### 3. Extract Search Results Logic

Move search highlighting logic to custom hook:

```typescript
const searchMatches = useSearchMatches(currentCanvas, searchTerm);
```

**Benefit:** Reusable, testable search logic

### 4. Performance Optimizations

* Lazy load large canvases
* Virtual scrolling for 100+ canvas works
* Web Workers for image processing
* Service Worker for offline viewing

**Benefit:** Better performance for large works

***

**See also:**

* [13-testing-strategy.md](https://github.com/wellcomecollection/docs/blob/main/rfcs/086-item-viewer-refactor/13-testing-strategy.md) - How to verify success
* [13-migration-checklist.md](/request-for-comments-rfcs/086-item-viewer-refactor/13-migration-checklist.md) - Track your progress

***

**Next:** [Future Improvements](/request-for-comments-rfcs/086-item-viewer-refactor/16-future-improvements.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.wellcomecollection.org/request-for-comments-rfcs/086-item-viewer-refactor/15-risks-and-success.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.