Skip to content

Local Docs Registry and Proxy Design

Purpose

This note defines a durable local cross-site documentation model for the OVES MkDocs workspace.

The current local review flow works, but it still depends on ad hoc per-repo mkdocs serve ports and partially manual coordination. The goal of this design is to make local cross-repo browsing stable without contaminating published documentation with localhost assumptions.

Problem Statement

The documentation hub and the underlying repo docs have two different needs:

  • Published documentation must use canonical cloud-safe links.
  • Local review must allow seamless navigation across multiple repos that are being served from a developer workstation.

The current implementation already moves in the right direction:

  • committed links stay canonical under https://docs.omnivoltaic.com/internal/<repo>
  • browser-side rewrite logic can swap the cloud root to a local proxy root on localhost
  • a workspace local-docs-registry.json exists outside the repo

However, the current model is still incomplete:

  • the browser rewrite logic does not consume the registry
  • repo availability and local port state are still external operational knowledge
  • there is no defined failure behavior when a repo is not reachable
  • local review still depends on manually tracking which repo is on which port

Goals

  • Keep all committed documentation links cloud-canonical.
  • Provide one stable local root for cross-site browsing.
  • Make repo-to-port or repo-to-target resolution a local infrastructure concern.
  • Use a single workspace registry as the source of truth for local docs routing state.
  • Support partial local availability, where some repos are running and others are not.
  • Make local failure states readable and actionable.

Non-Goals

  • Do not change published cloud routing behavior.
  • Do not make MkDocs source files carry localhost ports.
  • Do not require browser code in each repo to understand repo-specific routing.
  • Do not make consolidated-docs the owner of runtime process management for all repos.

Design Principles

Cloud-safe source

All source links in mkdocs.yml, docs/index.md, and generated hub content should continue to point at canonical documentation URLs.

Stable local origin

All local cross-site navigation should resolve through a single root, for example:

http://127.0.0.1:8099/internal/<repo>/

Infrastructure separation

Documentation repos own content. Local routing and process state belong to workspace infrastructure, not to the docs source.

Minimal browser logic

Browser-side logic should only detect local hosting and replace the canonical docs root with the shared local proxy root. It should not own route discovery, port lookup, or registry parsing.

Graceful degradation

If a repo is unavailable locally, the user should get a readable local diagnostic page instead of a low-level connection failure.

Proposed Architecture

The end-state architecture has four layers:

  1. Canonical docs source
  2. Local registry
  3. Local docs proxy
  4. Operational tooling

1. Canonical docs source

Each MkDocs repo, including consolidated-docs, continues to emit canonical links such as:

https://docs.omnivoltaic.com/internal/dirac-odoo

This keeps the source valid for published environments and avoids committing local workstation assumptions.

2. Local registry

The registry lives outside content repos, for example:

D:\github\git-workspace\local-docs-registry.json

The registry is the local environment manifest for documentation routing. It should define:

  • the canonical cloud docs root
  • the shared local proxy root
  • the known repo set
  • whether each repo is enabled for local routing
  • the local route target for each repo
  • optional metadata useful for status reporting

3. Local docs proxy

The proxy is the runtime gateway for local browsing. It owns:

  • reading the registry
  • serving a stable root such as /internal/<repo>/...
  • forwarding requests to the correct local repo docs target
  • returning local diagnostic pages when a target is unavailable

The proxy is the actual product boundary for local cross-site docs review. The registry is configuration. The docs repos remain content-only.

4. Operational tooling

A small set of workspace tools should manage the local docs environment. These tools should:

  • start or verify per-repo docs servers
  • update or validate registry state
  • start or verify the local proxy
  • report health and availability

This tooling should live in git-workspace or another infrastructure-oriented repo, not in consolidated-docs.

Component Responsibilities

consolidated-docs

Responsibilities:

  • publish canonical repo links
  • provide a minimal local rewrite script for localhost review
  • document the local browsing model

Must not:

  • own per-repo local port mapping
  • parse the workspace registry in the browser
  • become the source of truth for local docs runtime state

Browser-side resolver

Responsibilities:

  • detect local serving context
  • rewrite the canonical docs root to the configured local proxy root

Must not:

  • determine whether a repo is up
  • know the per-repo port map
  • fetch local routing state directly from workspace files

Registry

Responsibilities:

  • define known repos and their local routing targets
  • declare local enablement and metadata
  • define the shared roots used by proxy and tooling

Must not:

  • encode content or navigation concerns
  • become a published artifact consumed by cloud docs

Proxy

Responsibilities:

  • expose one stable local origin
  • translate repo routes into local runtime targets
  • centralize local failure handling
  • optionally expose status or diagnostics endpoints

Registry Schema

The registry should evolve from a simple port list into an explicit routing manifest.

Recommended fields:

{
  "version": 1,
  "roots": {
    "cloud_docs": "https://docs.omnivoltaic.com/internal",
    "local_docs_proxy": "http://127.0.0.1:8099/internal"
  },
  "repos": {
    "dirac-odoo": {
      "enabled": true,
      "target": {
        "type": "http",
        "base_url": "http://127.0.0.1:8000"
      },
      "source": {
        "repo_path": "D:\\github\\dirac-odoo"
      },
      "notes": "Current local review port"
    }
  }
}

Schema guidance:

  • version
  • supports future migration without ambiguous parsing
  • roots
  • defines canonical and local roots in one place
  • repos.<repo>.enabled
  • lets the proxy distinguish known-but-disabled from active
  • repos.<repo>.target
  • avoids hard-coding the idea that every route target is only host + port
  • repos.<repo>.source.repo_path
  • useful for status tools and launchers
  • repos.<repo>.notes
  • operational context only; not required for routing

The target.type field should allow future expansion if local docs are ever served through something other than a simple HTTP upstream.

Proxy Behavior

Routing model

Incoming local route:

/internal/<repo>/<path>

Routing behavior:

  1. Extract <repo>.
  2. Look up <repo> in the registry.
  3. If the repo is unknown, return a local 404 diagnostic page.
  4. If the repo is known but disabled, return a local disabled-state page.
  5. If the repo is enabled, proxy to the configured upstream target.
  6. If the upstream is unreachable, return a local unavailable-state page.

Required proxy behaviors

  • preserve path and query string
  • support trailing slash normalization
  • support assets, search index files, and other MkDocs static paths
  • avoid leaking low-level network errors directly to the user

The proxy should return readable pages for:

  • unknown repo
  • disabled repo
  • unreachable upstream

Each page should include:

  • repo name
  • expected local upstream
  • registry status
  • suggested next action

Example actions:

  • start the repo docs server
  • enable the repo in the registry
  • refresh the launcher/status tool

Browser Rewrite Behavior

The browser-side resolver should remain intentionally small.

Expected behavior:

  1. Detect whether the page is being served on localhost or 127.0.0.1.
  2. Rewrite links from: https://docs.omnivoltaic.com/internal/...
  3. To: http://127.0.0.1:8099/internal/...

That is enough. The proxy should own all repo-specific decisions beyond the root swap.

Launcher and Status Workflow

The local docs model needs operational support, otherwise the registry will drift from reality.

Launcher responsibilities

A launcher command should:

  • read the registry
  • optionally discover repo paths from the workspace
  • start local MkDocs servers for enabled repos that are not already running
  • allocate or validate ports
  • update registry state if runtime details change
  • start or verify the shared local proxy

Status responsibilities

A status command should report, per repo:

  • repo id
  • enabled or disabled
  • configured target
  • source path if known
  • live or unreachable
  • last check timestamp

This command is useful both for development and for debugging link failures.

Commands should be owned by workspace infrastructure, for example:

  • docs-local up
  • docs-local status
  • docs-local down
  • docs-local refresh-registry

The exact command names are flexible. The key point is that local docs orchestration should be explicit and repeatable.

Failure Modes and Handling

Repo not known

Cause:

  • hub links to a repo not present in the local registry

Response:

  • local 404 diagnostic page

Repo disabled

Cause:

  • repo exists in registry but local routing is intentionally turned off

Response:

  • local disabled-state page explaining that the route is known but inactive

Repo unreachable

Cause:

  • upstream server is not running or not responding

Response:

  • local unavailable page with target details and suggested recovery steps

Registry drift

Cause:

  • registry says a repo is on one port while the actual process is elsewhere

Response:

  • status tooling should detect drift
  • proxy diagnostics should expose the configured target
  • launcher should be able to repair or refresh the registry

Migration Plan

Phase 1: Formalize the design

  • publish this design note
  • keep canonical URLs in source unchanged
  • keep existing localhost root rewrite behavior

Phase 2: Strengthen the registry schema

  • move from host + port only to explicit target objects
  • add optional source-path metadata
  • define clear semantics for enabled

Phase 3: Make the proxy registry-driven

  • ensure the shared local proxy reads the registry directly
  • centralize unknown, disabled, and unavailable route handling

Phase 4: Add operational tooling

  • implement launcher and status commands
  • reduce manual per-repo mkdocs serve management
  • make registry refresh and diagnostics routine

Phase 5: Normalize team workflow

  • use the proxy root as the standard local cross-site docs entry point
  • stop relying on manually remembered ports during review

Security and Environment Considerations

  • Local routing logic should be active only in local review contexts.
  • Published source must not depend on developer workstation files.
  • Registry consumption should stay in local tooling or proxy infrastructure, not in published browser code.
  • Any future status or diagnostics endpoints should avoid exposing unnecessary local filesystem data unless explicitly intended for trusted internal use.

DevOps Backlog

Deployment environment manifest

Add an environment-controlled manifest for each deployment target. This manifest should be owned by deployment or workspace infrastructure, not by docs content.

The manifest should define at least:

  • canonical_docs_origin
  • local_docs_proxy_origin for local workspace use only
  • environment_mode such as local, internal-cloud, or client-cloud
  • optional feature flags for local-first resolution and fallback behavior

Examples:

  • internal cloud: https://docs.omnivoltaic.com
  • client-hosted cloud: https://docs.clientdomain.com
  • local workspace: http://127.0.0.1:8099

Canonical path discipline

Keep the hub and search artifacts deployment-agnostic.

  • search results should resolve to canonical docs paths, not developer-specific origins
  • committed content should never contain localhost
  • published cloud deployments must never point users to local workstation roots

Local-first with cloud fallback

For local review only:

  • the hub may compose a local candidate URL from the workspace-configured local proxy origin plus the canonical docs path
  • if the local target is not being served, the hub should fall back to the configured cloud docs origin
  • fallback should be fast and silent so the documentation tree still feels like one integrated system

For cloud deployments:

  • the deployment manifest should provide the correct cloud origin for that target
  • no local proxy behavior should be active
  • this must work for both OVES-hosted docs and service-hosted deployments on domains such as docs.clientdomain.com

DevOps implementation notes

Operationally, this means the DevOps owner should:

  • provide the deployment-time docs origin for each environment and target domain
  • ensure local workspace tooling can provide a developer-specific local proxy origin outside committed repo content
  • keep canonical docs path handling stable across all environments
  • verify that cloud deployments cannot emit or navigate to any localhost URL under any condition
  • verify that local review falls back to cloud cleanly when a child docs site is not being served

Open Questions

  • Which repo should own the proxy implementation long-term?
  • Should launcher tooling assign ports dynamically or preserve stable preferred ports?
  • Should the registry be edited directly, or should tooling treat it as generated state?
  • Should the proxy expose a machine-readable health endpoint in addition to HTML diagnostics?

Adopt the proxy-centered model.

Specifically:

  • keep canonical cloud links in all committed docs source
  • keep browser-side rewrite logic limited to cloud-root to proxy-root replacement
  • treat the workspace registry as the single local routing manifest
  • make the shared local proxy consume that registry
  • add small operational tools around proxy and registry health

This approach solves the local cross-site review problem at the right layer. It avoids embedding workstation routing concerns into published docs while giving developers a stable and debuggable local browsing model.