docling-studio/docs/design/207-document-centric-routing.md

Design: Document-centric routing

• Issue: #207
• Title on issue: [FEATURE] Document-centric routing (/docs, /docs/:id?mode=, /index/:store, /runs)
• Author: Pier-Jean Malandrino
• Date: 2026-04-29
• Status: Accepted
• Target milestone: 0.6.0 — Doc-centric ingest
• Impacted layers: frontend: app/router · pages · shared
• Audit dimensions likely touched: Clean Code · Tests · Documentation
• ADR spawned?: no

---

1. Problem

The current Vue Router (frontend/src/app/router/index.ts) is analysis-centric: routes are /studio, /documents, /search, /reasoning, /history. The selected document is held in a Pinia store, not in the URL — so two engineers cannot share a link to "the chunks editor for doc X". This breaks the killer flow ("paste this URL → fix the chunks → re-ingest") that 0.6.0 promises.

The 0.6.0 sitemap puts the document at the centre of every URL: /docs, /docs/:id?mode=ask|inspect|chunks, plus /index/:store for stores and /runs for the run history. Mode is a query param so a doc URL stays stable across mode switches.

This issue ships the routing skeleton. The actual page contents come in E3 (/docs library — #211), E4 (workspace shell — #216), E5 (chunks editor — #218 onward).

2. Goals

• Add /docs, /docs/new, /docs/:id, /index, /index/:store, /index/:store/query, /runs, /runs/:id routes.
• On /docs/:id, ?mode=ask|inspect|chunks is parsed; default = ask.
• Each new route renders a placeholder page (clear "Coming in 0.6.0" message) until E3/E4/E5 implement them.
• Legacy routes (/studio, /documents, /history, /search, /reasoning) keep working — no breaking redirect in this issue.
• Smoke test: each new route renders without error.

3. Non-goals

• Building the actual pages — that is E3 / E4 / E5.
• Migrating users from old routes — kept functional in parallel; deprecation comes when the new pages are ready.
• Server-side route enforcement — backend exposes its API on /api/*; the routing here is client-side only.
• A site map / generated nav — the sidebar nav rework is #209.
• Feature-flag-aware redirection (e.g. mode disabled → redirect to default) — that is #210.

4. Context & constraints

Existing code surface

• frontend/src/app/router/index.ts — current Vue Router setup (history mode, lazy-loaded pages).
• frontend/src/pages/ — existing pages (HomePage.vue, StudioPage.vue, DocumentsPage.vue, HistoryPage.vue, SearchPage.vue, ReasoningPage.vue, SettingsPage.vue).
• frontend/src/app/App.vue — shell with topbar + sidebar + <RouterView />.
• frontend/src/features/feature-flags/ — flag store and useFeatureFlag composable.

Hard constraints

• TypeScript strict — every new route needs a typed name.
• No regression on existing routes — old URLs keep returning their current pages until #211 / #216 explicitly replace them.
• Lazy loading is preserved — every new page goes through () => import(...).

Deployment modes

Same routing for both latest-local and latest-remote. No HF Space-specific concern.

5. Proposed design

5.1 Router additions

Append to frontend/src/app/router/index.ts:

{ path: '/docs', name: 'docs-library',
  component: () => import('@/pages/DocsLibraryPage.vue') },
{ path: '/docs/new', name: 'docs-new',
  component: () => import('@/pages/DocsNewPage.vue') },
{ path: '/docs/:id', name: 'doc-workspace',
  component: () => import('@/pages/DocWorkspacePage.vue'),
  props: route => ({ id: route.params.id, mode: parseMode(route.query.mode) }) },
{ path: '/index', name: 'stores-list',
  component: () => import('@/pages/StoresListPage.vue') },
{ path: '/index/:store', name: 'store-detail',
  component: () => import('@/pages/StoreDetailPage.vue'),
  props: true },
{ path: '/index/:store/query', name: 'store-query',
  component: () => import('@/pages/StoreQueryPage.vue'),
  props: true },
{ path: '/runs', name: 'runs',
  component: () => import('@/pages/RunsPage.vue') },
{ path: '/runs/:id', name: 'run-detail',
  component: () => import('@/pages/RunDetailPage.vue'),
  props: true },

5.2 Mode parser

A pure helper in frontend/src/shared/routing/modes.ts:

export type DocMode = 'ask' | 'inspect' | 'chunks'
const DEFAULT_MODE: DocMode = 'ask'

export function parseMode(raw: unknown): DocMode {
  return raw === 'inspect' || raw === 'chunks' ? raw : DEFAULT_MODE
}

This is intentionally tiny and testable. #210 will extend it with feature-flag-aware redirection.

5.3 Placeholder pages

Each new page is ~30 lines of Vue: a centered card with the page title, a "Coming in 0.6.0" tagline, and a link back to home. They use the existing useI18n() strings under a new comingSoon.* namespace.

5.4 Router types

frontend/src/shared/routing/names.ts exports a typed union of route names so callers do router.push({ name: ROUTES.DOC_WORKSPACE, params: { id } }) instead of stringly-typed names.

export const ROUTES = {
  HOME: 'home',
  DOCS_LIBRARY: 'docs-library',
  DOCS_NEW: 'docs-new',
  DOC_WORKSPACE: 'doc-workspace',
  STORES_LIST: 'stores-list',
  STORE_DETAIL: 'store-detail',
  STORE_QUERY: 'store-query',
  RUNS: 'runs',
  RUN_DETAIL: 'run-detail',
  // ...legacy names kept as-is
} as const
export type RouteName = (typeof ROUTES)[keyof typeof ROUTES]

5.5 i18n

New keys under comingSoon.* in frontend/src/shared/i18n.ts (fr + en):

• comingSoon.title
• comingSoon.subtitle.docsLibrary
• comingSoon.subtitle.docsNew
• comingSoon.subtitle.docWorkspace
• comingSoon.subtitle.stores
• comingSoon.subtitle.storeDetail
• comingSoon.subtitle.storeQuery
• comingSoon.subtitle.runs
• comingSoon.subtitle.runDetail
• comingSoon.backHome

6. Alternatives considered

Alternative A — Replace existing routes immediately

• Summary: Make /studio and /documents redirect to the new routes in this issue.
• Why not: The new pages do not exist yet. Redirecting now means the user lands on a "Coming soon" page where they used to have a working app.

Alternative B — Hash-mode routing

• Summary: Switch to createWebHashHistory for the new doc-centric routes.
• Why not: History mode is the existing convention and SPA deep-linking still works behind Nginx (already configured). No reason to mix modes.

7. API & data contract

No backend changes. The routes are entirely client-side. No env vars.

Breaking changes

None. Additive.

8. Risks & mitigations

Risk	Audit dimension	Likelihood	Impact	How we notice	Mitigation / rollback
Placeholder pages confuse users who land on them via shared links	Documentation	Medium	Low	Support tickets	Clear "Coming soon" copy + back-home link
Route name collisions with legacy ones	Clean Code	Low	Low	TS error / runtime warning	Use a ROUTES constant; legacy names kept
Broken nav from sidebar to legacy routes after rename	Decoupling	Low	Medium	Smoke test catches	The sidebar update is explicitly #209, not this issue

9. Testing strategy

Frontend — Vitest

• app/router/router.test.ts — every new route resolves to its component (smoke).
• shared/routing/modes.test.ts — parseMode returns ask for undefined / null / unknown values; respects inspect / chunks.

E2E — Karate UI

Out of scope for this issue (placeholder pages only). E2E coverage lands with #211 (library) and #216 (workspace).

Manual QA

1. Visit each new URL in the browser → "Coming soon" shell renders without 404.
2. Visit /docs/abc?mode=chunks → page receives mode === 'chunks'.
3. Visit /docs/abc?mode=garbage → page receives mode === 'ask' (default).
4. Old routes (/studio, /documents) still load their existing pages.

10. Rollout & observability

Release branch

release/0.6.0.

Feature flag

None. The placeholder pages are visible to anyone; they explain themselves.

Observability

No new logs. Existing router-error handling unchanged.

Rollback plan

Revert the router and pages — old setup is untouched.

11. Open questions

• Should /docs/:id 404 if the doc id is unknown, or render the workspace shell with an error state? Decision for 0.6.0: the workspace handles the "doc not found" case in #216; this issue ships the placeholder which always renders.

12. References

• Issue: https://github.com/scub-france/Docling-Studio/issues/207
• Related issues: #208 (breadcrumb), #209 (nav), #210 (FF mode gating), #211 (library page), #216 (workspace), #218+ (modes)
• ADRs: none planned
• Project docs:
  • Architecture: docs/architecture.md
  • Frontend conventions: frontend/CLAUDE.md