Skip to main content

Feature: Evidence Link Construction

Purpose​

  • Feature name: Evidence link construction
  • Why this feature exists: Ensure evidence links are constructed consistently across preview, staging, and production environments.

Scope​

In scope​

  • docs base URL configuration
  • helper functions for docs and GitHub links
  • environment-safe link building

Out of scope​

  • evidence rendering UI (covered in evidence visualization)
  • project registry validation logic

Prereqs / Inputs​

  • NEXT_PUBLIC_DOCS_BASE_URL configured
  • optional NEXT_PUBLIC_GITHUB_URL and NEXT_PUBLIC_DOCS_GITHUB_URL

Procedure / Content​

Feature summary​

  • Feature name: Evidence link construction
  • Feature group: Evidence-first content model
  • Technical summary: Uses centralized helpers to build docs and repo URLs from public environment variables.
  • Low-tech summary: Keeps links consistent no matter which environment is deployed.

Feature in action​

  • Where to see it working: Evidence links on /projects/[slug] and /cv pages.

Confirmation Process​

Manual​

  • Steps: Open a project page and click dossier and ADR links.
  • What to look for: Links point to the expected docs base URL across environments.
  • Artifacts or reports to inspect: Environment variable values, E2E evidence-link DOM assertions, and optional external-link monitor runs for live reachability.

Tests​

Potential behavior if broken or misconfigured​

  • Evidence links point to localhost in production.
  • Missing docs base URL falls back to /docs unexpectedly.

Long-term maintenance notes​

  • Keep environment variables documented and validated.
  • Re-check link construction when domain strategy changes.

Dependencies, libraries, tools​

  • Next.js App Router
  • React
  • Vercel (environment variables)

Source code references (GitHub URLs)​

ADRs​

  • None.

Runbooks​

  • None.

Additional internal references​

Validation / Expected outcomes​

  • Evidence links are built with the correct base URL and expected paths in preview, staging, and production.
  • Docs base URL changes do not require code changes.

Failure modes / Troubleshooting​

  • Incorrect docs host: update environment variables and redeploy.
  • Broken link helpers: fix config tests and re-run CI.

References​

  • None.