From 2b65892c82132be9c2c777720acf8e94c2cf0b40 Mon Sep 17 00:00:00 2001
From: Igor Octaviano <igoroctaviano@gmail.com>
Date: Mon, 22 Jun 2026 19:40:20 -0300
Subject: [PATCH] feat: abstract routing configuration and URI parameter access
 (#48)

Introduce src/utils/routes.ts as a single source of truth for route
templates, path builders, and URI parameter parsing. Previously the
/studies/:studyInstanceUID/series/:seriesInstanceUID template (and its
GCP DICOM store variant) was hardcoded and re-parsed by hand across
App, CaseViewer, Worklist, Header, and OidcManager, making routing
changes error-prone.

Components now consume RoutePaths for <Route> definitions and the
buildStudyPath/buildSeriesPath/buildLogoutPath builders plus
parse/predicate helpers instead of ad-hoc string interpolation,
split(), includes(), and regex replacement.

Add unit tests for the new routing helpers.

Closes #48
---
 src/App.tsx                        |  13 +--
 src/auth/OidcManager.tsx           |   5 +-
 src/components/CaseViewer.tsx      |  35 +++----
 src/components/Header.tsx          |  28 ++----
 src/components/Worklist.tsx        |   3 +-
 src/utils/__tests__/routes.test.ts | 115 +++++++++++++++++++++++
 src/utils/routes.ts                | 144 +++++++++++++++++++++++++++++
 7 files changed, 296 insertions(+), 47 deletions(-)
 create mode 100644 src/utils/__tests__/routes.test.ts
 create mode 100644 src/utils/routes.ts

diff --git a/src/App.tsx b/src/App.tsx
index 70f0cde4..d90f7a42 100644
--- a/src/App.tsx
+++ b/src/App.tsx
@@ -28,6 +28,7 @@ import NotificationMiddleware, {
   NotificationMiddlewareContext,
 } from './services/NotificationMiddleware'
 import { CustomError, errorTypes } from './utils/CustomError'
+import { getProjectStorePath, isProjectsPath, RoutePaths } from './utils/routes'
 import { joinUrl, normalizeServerUrl } from './utils/url'
 
 function ParametrizedCaseViewer({
@@ -103,8 +104,8 @@ function _createClientMapping({
         }
       })
     } else {
-      if (window.location.pathname.includes('/projects/')) {
-        const pathname = window.location.pathname.split('/study/')[0]
+      if (isProjectsPath(window.location.pathname)) {
+        const pathname = getProjectStorePath(window.location.pathname)
         const pathUrl = `${gcpBaseUrl}${pathname}/dicomWeb`
         serverSettings.url = pathUrl
       }
@@ -540,7 +541,7 @@ class App extends React.Component<AppProps, AppState> {
         <BrowserRouter basename={this.props.config.path}>
           <Routes>
             <Route
-              path="/"
+              path={RoutePaths.ROOT}
               element={
                 <Layout style={layoutStyle}>
                   <Header
@@ -563,7 +564,7 @@ class App extends React.Component<AppProps, AppState> {
               }
             />
             <Route
-              path="/studies/:studyInstanceUID/*"
+              path={RoutePaths.STUDY}
               element={
                 <SettingsProvider>
                   <Layout style={layoutStyle}>
@@ -593,7 +594,7 @@ class App extends React.Component<AppProps, AppState> {
               }
             />
             <Route
-              path="/projects/:project/locations/:location/datasets/:dataset/dicomStores/:dicomStore/study/:studyInstanceUID/*"
+              path={RoutePaths.GCP_STUDY}
               element={
                 <SettingsProvider>
                   <Layout style={layoutStyle}>
@@ -623,7 +624,7 @@ class App extends React.Component<AppProps, AppState> {
               }
             />
             <Route
-              path="/logout"
+              path={RoutePaths.LOGOUT}
               element={
                 <Layout style={layoutStyle}>
                   <Header
diff --git a/src/auth/OidcManager.tsx b/src/auth/OidcManager.tsx
index d1d4fedc..4dfd97fd 100644
--- a/src/auth/OidcManager.tsx
+++ b/src/auth/OidcManager.tsx
@@ -5,6 +5,7 @@ import NotificationMiddleware, {
   NotificationMiddlewareContext,
 } from '../services/NotificationMiddleware'
 import { CustomError, errorTypes } from '../utils/CustomError'
+import { buildLogoutPath } from '../utils/routes'
 import { isAuthorizationCodeInUrl } from '../utils/url'
 import type { AuthManager, SignInCallback, User } from '.'
 
@@ -63,7 +64,7 @@ export default class OidcManager implements AuthManager {
       loadUserInfo: true,
       automaticSilentRenew: true,
       revokeAccessTokenOnSignout: true,
-      post_logout_redirect_uri: `${baseUri}/logout`,
+      post_logout_redirect_uri: buildLogoutPath(baseUri),
     })
     if (
       settings.endSessionEndpoint !== null &&
@@ -95,7 +96,7 @@ export default class OidcManager implements AuthManager {
               loadUserInfo: true,
               automaticSilentRenew: true,
               revokeAccessTokenOnSignout: true,
-              post_logout_redirect_uri: `${baseUri}/logout`,
+              post_logout_redirect_uri: buildLogoutPath(baseUri),
               metadata,
             })
           }
diff --git a/src/components/CaseViewer.tsx b/src/components/CaseViewer.tsx
index c9ca3738..8b150c9a 100644
--- a/src/components/CaseViewer.tsx
+++ b/src/components/CaseViewer.tsx
@@ -11,6 +11,14 @@ import type { Slide } from '../data/slides'
 import { StorageClasses } from '../data/uids'
 import { useSlides } from '../hooks/useSlides'
 import { type RouteComponentProps, withRouter } from '../utils/router'
+import {
+  buildSeriesPath,
+  hasSeriesInPath,
+  isProjectsPath,
+  parseSeriesInstanceUID,
+  RoutePaths,
+  withSeriesInProjectPath,
+} from '../utils/routes'
 import ClinicalTrial from './ClinicalTrial'
 import Patient from './Patient'
 import SlideList from './SlideList'
@@ -215,22 +223,14 @@ function Viewer(props: ViewerProps): JSX.Element | null {
     seriesInstanceUID: string
   }): void => {
     console.info(`switch to series "${seriesInstanceUID}"`)
-    let urlPath = `/studies/${studyInstanceUID}/series/${seriesInstanceUID}`
+    let urlPath = buildSeriesPath(studyInstanceUID, seriesInstanceUID)
 
-    if (location.pathname.includes('/projects/')) {
-      urlPath = location.pathname
-      if (!location.pathname.includes('/series/')) {
-        urlPath += `/series/${seriesInstanceUID}`
-      } else {
-        urlPath = urlPath.replace(
-          /\/series\/[^/]+/,
-          `/series/${seriesInstanceUID}`,
-        )
-      }
+    if (isProjectsPath(location.pathname)) {
+      urlPath = withSeriesInProjectPath(location.pathname, seriesInstanceUID)
     }
 
     if (
-      location.pathname.includes('/series/') &&
+      hasSeriesInPath(location.pathname) &&
       location.search !== null &&
       location.search !== undefined
     ) {
@@ -259,13 +259,8 @@ function Viewer(props: ViewerProps): JSX.Element | null {
    * Otherwise select the first series correspondent to
    * the first slide contained in the study.
    */
-  let selectedSeriesInstanceUID: string
-  if (location.pathname.includes('series/')) {
-    const seriesFragment = location.pathname.split('series/')[1]
-    selectedSeriesInstanceUID = seriesFragment.includes('/')
-      ? seriesFragment.split('/')[0]
-      : seriesFragment
-  } else {
+  let selectedSeriesInstanceUID = parseSeriesInstanceUID(location.pathname)
+  if (selectedSeriesInstanceUID === '') {
     selectedSeriesInstanceUID = volumeInstances[0].SeriesInstanceUID
   }
 
@@ -316,7 +311,7 @@ function Viewer(props: ViewerProps): JSX.Element | null {
 
       <Routes>
         <Route
-          path="/series/:seriesInstanceUID"
+          path={RoutePaths.SERIES}
           element={
             <ParametrizedSlideViewer
               clients={props.clients}
diff --git a/src/components/Header.tsx b/src/components/Header.tsx
index 2337f056..fe8ec199 100644
--- a/src/components/Header.tsx
+++ b/src/components/Header.tsx
@@ -36,6 +36,11 @@ import NotificationMiddleware, {
 } from '../services/NotificationMiddleware'
 import type { CustomError } from '../utils/CustomError'
 import { type RouteComponentProps, withRouter } from '../utils/router'
+import {
+  isGcpDicomStorePath,
+  isViewerPath,
+  parseSeriesInstanceUID,
+} from '../utils/routes'
 import { normalizeServerUrl } from '../utils/url'
 import Button from './Button'
 import DicomTagBrowser from './DicomTagBrowser/DicomTagBrowser'
@@ -45,8 +50,6 @@ const aboutModalCopyTooltips: [React.ReactNode, React.ReactNode] = [
   'Copied!',
 ]
 
-const DICOM_TAG_BROWSER_PATHS = ['/studies/', '/study/', '/projects/'] as const
-
 const aboutModalStyles: Record<string, React.CSSProperties> = {
   container: {
     textAlign: 'center',
@@ -213,12 +216,7 @@ class Header extends React.Component<HeaderProps, HeaderState> {
       }
     }
     const pathNorm = trimmedUrl.startsWith('/') ? trimmedUrl : `/${trimmedUrl}`
-    return (
-      pathNorm.includes('/projects/') &&
-      pathNorm.includes('/locations/') &&
-      pathNorm.includes('/datasets/') &&
-      pathNorm.includes('/dicomStores/')
-    )
+    return isGcpDicomStorePath(pathNorm)
   }
 
   static handleUserMenuButtonClick(e: React.SyntheticEvent): void {
@@ -367,13 +365,9 @@ class Header extends React.Component<HeaderProps, HeaderState> {
   handleDicomTagBrowserButtonClick = (): void => {
     const width = window.innerWidth - 200
 
-    let seriesInstanceUID = ''
-    if (this.props.location.pathname.includes('series/')) {
-      const seriesFragment = this.props.location.pathname.split('series/')[1]
-      seriesInstanceUID = seriesFragment.includes('/')
-        ? seriesFragment.split('/')[0]
-        : seriesFragment
-    }
+    const seriesInstanceUID = parseSeriesInstanceUID(
+      this.props.location.pathname,
+    )
 
     Modal.info({
       title: 'DICOM Tag Browser',
@@ -627,9 +621,7 @@ class Header extends React.Component<HeaderProps, HeaderState> {
       </Badge>
     )
 
-    const showDicomTagBrowser = DICOM_TAG_BROWSER_PATHS.some((path) =>
-      this.props.location.pathname.includes(path),
-    )
+    const showDicomTagBrowser = isViewerPath(this.props.location.pathname)
 
     const dicomTagBrowserButton = showDicomTagBrowser ? (
       <Button
diff --git a/src/components/Worklist.tsx b/src/components/Worklist.tsx
index 43a7718e..a6bf37c0 100644
--- a/src/components/Worklist.tsx
+++ b/src/components/Worklist.tsx
@@ -14,6 +14,7 @@ import NotificationMiddleware, {
 import { CustomError, errorTypes } from '../utils/CustomError'
 import { logger } from '../utils/logger'
 import { type RouteComponentProps, withRouter } from '../utils/router'
+import { buildStudyPath } from '../utils/routes'
 import { parseDate, parseName, parseSex, parseTime } from '../utils/values'
 
 // Standalone function for row key generation
@@ -125,7 +126,7 @@ class Worklist extends React.Component<WorklistProps, WorklistState> {
     _event: React.SyntheticEvent,
     study: dmv.metadata.Study,
   ): void => {
-    this.props.navigate(`/studies/${study.StudyInstanceUID}`)
+    this.props.navigate(buildStudyPath(study.StudyInstanceUID))
   }
 
   fetchData = ({
diff --git a/src/utils/__tests__/routes.test.ts b/src/utils/__tests__/routes.test.ts
new file mode 100644
index 00000000..7ff31f68
--- /dev/null
+++ b/src/utils/__tests__/routes.test.ts
@@ -0,0 +1,115 @@
+import {
+  buildLogoutPath,
+  buildSeriesPath,
+  buildStudyPath,
+  getProjectStorePath,
+  hasSeriesInPath,
+  isGcpDicomStorePath,
+  isProjectsPath,
+  isViewerPath,
+  parseSeriesInstanceUID,
+  RouteParams,
+  RoutePaths,
+  withSeriesInProjectPath,
+} from '../routes'
+
+const studyUID = '1.2.3'
+const seriesUID = '4.5.6'
+const otherSeriesUID = '7.8.9'
+
+const gcpStorePath =
+  '/projects/idc-sandbox-000/locations/us-central1/datasets/dev/dicomStores/store'
+
+describe('route templates', () => {
+  it('embed the configured parameter names', () => {
+    expect(RoutePaths.STUDY).toBe(`/studies/:${RouteParams.STUDY_INSTANCE_UID}/*`)
+    expect(RoutePaths.SERIES).toBe(
+      `/series/:${RouteParams.SERIES_INSTANCE_UID}`,
+    )
+    expect(RoutePaths.GCP_STUDY).toBe(
+      '/projects/:project/locations/:location/datasets/:dataset/dicomStores/:dicomStore/study/:studyInstanceUID/*',
+    )
+    expect(RoutePaths.ROOT).toBe('/')
+    expect(RoutePaths.LOGOUT).toBe('/logout')
+  })
+})
+
+describe('path builders', () => {
+  it('builds study paths', () => {
+    expect(buildStudyPath(studyUID)).toBe('/studies/1.2.3')
+  })
+
+  it('builds series paths', () => {
+    expect(buildSeriesPath(studyUID, seriesUID)).toBe(
+      '/studies/1.2.3/series/4.5.6',
+    )
+  })
+
+  it('builds logout paths', () => {
+    expect(buildLogoutPath('https://example.org')).toBe(
+      'https://example.org/logout',
+    )
+  })
+})
+
+describe('parseSeriesInstanceUID', () => {
+  it('returns the series UID at the end of a path', () => {
+    expect(parseSeriesInstanceUID('/studies/1.2.3/series/4.5.6')).toBe(seriesUID)
+  })
+
+  it('returns the series UID followed by further segments', () => {
+    expect(parseSeriesInstanceUID('/studies/1.2.3/series/4.5.6/extra')).toBe(
+      seriesUID,
+    )
+  })
+
+  it('returns an empty string when no series is present', () => {
+    expect(parseSeriesInstanceUID('/studies/1.2.3')).toBe('')
+  })
+})
+
+describe('path predicates', () => {
+  it('detects series in a path', () => {
+    expect(hasSeriesInPath('/studies/1.2.3/series/4.5.6')).toBe(true)
+    expect(hasSeriesInPath('/studies/1.2.3')).toBe(false)
+  })
+
+  it('detects GCP project paths', () => {
+    expect(isProjectsPath(`${gcpStorePath}/study/1.2.3`)).toBe(true)
+    expect(isProjectsPath('/studies/1.2.3')).toBe(false)
+  })
+
+  it('detects viewer paths', () => {
+    expect(isViewerPath('/studies/1.2.3')).toBe(true)
+    expect(isViewerPath(`${gcpStorePath}/study/1.2.3`)).toBe(true)
+    expect(isViewerPath('/')).toBe(false)
+  })
+
+  it('detects GCP DICOM store paths', () => {
+    expect(isGcpDicomStorePath(gcpStorePath)).toBe(true)
+    expect(isGcpDicomStorePath('/projects/foo')).toBe(false)
+  })
+})
+
+describe('getProjectStorePath', () => {
+  it('returns the store path up to the study segment', () => {
+    expect(getProjectStorePath(`${gcpStorePath}/study/1.2.3`)).toBe(gcpStorePath)
+  })
+})
+
+describe('withSeriesInProjectPath', () => {
+  it('appends a series segment when none is present', () => {
+    expect(
+      withSeriesInProjectPath(`${gcpStorePath}/study/1.2.3`, seriesUID),
+    ).toBe(`${gcpStorePath}/study/1.2.3/series/4.5.6`)
+  })
+
+  it('replaces an existing series segment', () => {
+    expect(
+      withSeriesInProjectPath(
+        `${gcpStorePath}/study/1.2.3/series/${otherSeriesUID}`,
+        seriesUID,
+      ),
+    ).toBe(`${gcpStorePath}/study/1.2.3/series/4.5.6`)
+  })
+})
diff --git a/src/utils/routes.ts b/src/utils/routes.ts
new file mode 100644
index 00000000..06b543b8
--- /dev/null
+++ b/src/utils/routes.ts
@@ -0,0 +1,144 @@
+/**
+ * Centralized routing configuration.
+ *
+ * Abstracts the URI templates and parameter names that were previously
+ * hardcoded across the app, see
+ * https://github.com/ImagingDataCommons/slim/issues/48.
+ *
+ * All route definitions, path construction, and URI parameter parsing should go
+ * through this module so the routing scheme can be changed in a single place
+ * instead of being duplicated (and re-parsed by hand) in multiple components.
+ */
+
+/** Names of the dynamic parameters embedded in the route templates. */
+export const RouteParams = {
+  STUDY_INSTANCE_UID: 'studyInstanceUID',
+  SERIES_INSTANCE_UID: 'seriesInstanceUID',
+  PROJECT: 'project',
+  LOCATION: 'location',
+  DATASET: 'dataset',
+  DICOM_STORE: 'dicomStore',
+} as const
+
+/** Path segments used to build and recognize routes. */
+const Segments = {
+  studies: 'studies',
+  series: 'series',
+  logout: 'logout',
+  // GCP Healthcare DICOM store path segments.
+  projects: 'projects',
+  locations: 'locations',
+  datasets: 'datasets',
+  dicomStores: 'dicomStores',
+  study: 'study',
+} as const
+
+/**
+ * Route templates consumed by react-router `<Route path>` definitions.
+ * `:name` placeholders correspond to entries in `RouteParams`.
+ */
+export const RoutePaths = {
+  /** Worklist / landing page. */
+  ROOT: '/',
+  /** Study viewer (DICOMweb). Trailing `/*` enables nested series routes. */
+  STUDY: `/${Segments.studies}/:${RouteParams.STUDY_INSTANCE_UID}/*`,
+  /** Study viewer addressed via a GCP Healthcare DICOM store path. */
+  GCP_STUDY:
+    `/${Segments.projects}/:${RouteParams.PROJECT}` +
+    `/${Segments.locations}/:${RouteParams.LOCATION}` +
+    `/${Segments.datasets}/:${RouteParams.DATASET}` +
+    `/${Segments.dicomStores}/:${RouteParams.DICOM_STORE}` +
+    `/${Segments.study}/:${RouteParams.STUDY_INSTANCE_UID}/*`,
+  /** Series viewer, nested under a study route. */
+  SERIES: `/${Segments.series}/:${RouteParams.SERIES_INSTANCE_UID}`,
+  /** Post-logout landing page. */
+  LOGOUT: `/${Segments.logout}`,
+} as const
+
+const SERIES_PREFIX = `${Segments.series}/`
+const SERIES_PATH_PREFIX = `/${Segments.series}/`
+const PROJECTS_PATH_PREFIX = `/${Segments.projects}/`
+const STUDY_PATH_PREFIX = `/${Segments.study}/`
+const SERIES_SEGMENT_PATTERN = new RegExp(`/${Segments.series}/[^/]+`)
+
+/** Builds the absolute path to a study's viewer. */
+export const buildStudyPath = (studyInstanceUID: string): string =>
+  `/${Segments.studies}/${studyInstanceUID}`
+
+/** Builds the absolute path to a series within a study's viewer. */
+export const buildSeriesPath = (
+  studyInstanceUID: string,
+  seriesInstanceUID: string,
+): string =>
+  `${buildStudyPath(studyInstanceUID)}/${Segments.series}/${seriesInstanceUID}`
+
+/** Builds the absolute logout path for a given base URI. */
+export const buildLogoutPath = (baseUri: string): string =>
+  `${baseUri}/${Segments.logout}`
+
+/** Whether a pathname encodes a series segment. */
+export const hasSeriesInPath = (pathname: string): boolean =>
+  pathname.includes(SERIES_PATH_PREFIX)
+
+/** Whether a pathname is a GCP DICOM store ("projects") path. */
+export const isProjectsPath = (pathname: string): boolean =>
+  pathname.includes(PROJECTS_PATH_PREFIX)
+
+/**
+ * Extracts the SeriesInstanceUID from a pathname, or '' when none is present.
+ * Handles both `.../series/<uid>` and `.../series/<uid>/...` forms.
+ */
+export const parseSeriesInstanceUID = (pathname: string): string => {
+  if (!pathname.includes(SERIES_PREFIX)) {
+    return ''
+  }
+  const seriesFragment = pathname.split(SERIES_PREFIX)[1]
+  return seriesFragment.includes('/')
+    ? seriesFragment.split('/')[0]
+    : seriesFragment
+}
+
+/**
+ * Returns the portion of a GCP project pathname up to (but excluding) the
+ * `/study/` segment. Used to derive the DICOMweb base URL from the URL.
+ */
+export const getProjectStorePath = (pathname: string): string =>
+  pathname.split(STUDY_PATH_PREFIX)[0]
+
+/**
+ * Replaces the series segment in a GCP project pathname, or appends one when the
+ * pathname does not yet encode a series.
+ */
+export const withSeriesInProjectPath = (
+  pathname: string,
+  seriesInstanceUID: string,
+): string => {
+  if (!hasSeriesInPath(pathname)) {
+    return `${pathname}${SERIES_PATH_PREFIX}${seriesInstanceUID}`
+  }
+  return pathname.replace(
+    SERIES_SEGMENT_PATTERN,
+    `${SERIES_PATH_PREFIX}${seriesInstanceUID}`,
+  )
+}
+
+/** Path prefixes for which the DICOM Tag Browser button is shown. */
+export const DICOM_TAG_BROWSER_PATHS = [
+  `/${Segments.studies}/`,
+  `/${Segments.study}/`,
+  `/${Segments.projects}/`,
+] as const
+
+/** Whether the current pathname corresponds to a study/series viewer. */
+export const isViewerPath = (pathname: string): boolean =>
+  DICOM_TAG_BROWSER_PATHS.some((path) => pathname.includes(path))
+
+/**
+ * Whether a string looks like a GCP Healthcare DICOM store path, i.e. it
+ * contains the projects/locations/datasets/dicomStores segments.
+ */
+export const isGcpDicomStorePath = (pathname: string): boolean =>
+  pathname.includes(PROJECTS_PATH_PREFIX) &&
+  pathname.includes(`/${Segments.locations}/`) &&
+  pathname.includes(`/${Segments.datasets}/`) &&
+  pathname.includes(`/${Segments.dicomStores}/`)