Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt

Use this file to discover all available pages before exploring further.

This document defines how canonical URLs and host canonicalization work for the Encore Health OS platform. It is part of the broader Multi-Tenant Host & URL Strategy (PF-81).

​
In-app canonical URLs (PF-74)

  • Slug URLs are canonical. When a user accesses /o/:orgSlug/..., the app resolves the organization, sets context, and renders the requested page in place. The URL is not changed to a flat path (e.g. /hr/employees). This preserves shareable links, browser history, and deep-link stability.
  • Flat routes (e.g. /hr/employees) remain supported for backward compatibility. They do not redirect to slug URLs by default. Components that generate internal links should prefer useOrgPath() or orgPath(slug, path) so that users who arrived via a slug URL stay in slug space.

​
Host canonicalization (PF-77)

When the platform or a tenant uses a custom domain, one canonical host should be chosen to avoid duplicate content and inconsistent session behavior.

​
Apex vs www

  • Choose one canonical host per deployment: either the apex domain (e.g. app.encoreos.io) or the www variant (e.g. www.app.encoreos.io), not both.
  • Configure redirects so that the non-canonical host redirects (301/308) to the canonical host. This is typically done in the Vercel project → Settings → Domains (add both apex and www, then set a domain redirect from the non-canonical to the canonical). Alternatively, use Vercel redirects in vercel.json or in the dashboard when the same project serves both hosts.
  • Cookie scope: Ensure session cookies are set on the canonical host (or with a shared parent domain) so that redirects between apex and www do not drop the session.

​
Subdomain vs custom domain (multi-tenant)

  • If both a platform subdomain (e.g. tenant.platform.com) and a tenant custom domain (e.g. app.tenant.com) serve the same tenant, either:
    • Redirect one to the other (e.g. redirect subdomain to custom domain), or
    • Set a canonical URL in the HTML <head> (e.g. <link rel="canonical" href="https://app.tenant.com/..." />) to indicate the official URL and avoid search-engine duplicate content.
  • Path-based org routing (PF-74) uses /o/:orgSlug/...; host canonicalization is relevant when custom domains (PF-77) are in use.

​
References