ADR 003: Cross-App Links

Status

Accepted

Context

With the subdomain architecture, each app runs on:

• Different ports in development (localhost:4320, localhost:4322, etc.)
• Different subdomains in production (lakea.dev, docs.lakea.dev, etc.)

We need a simple way to generate correct links between apps.

Decision

Use getAppLink(appId, path) from @lakea/core:

import { getAppLink } from '@lakea/core';

// In development (detected automatically)
getAppLink('handbook')           // 'http://localhost:4322/'
getAppLink('handbook', '/start') // 'http://localhost:4322/start'

// In production
getAppLink('handbook')           // 'https://docs.lakea.dev/'
getAppLink('handbook', '/start') // 'https://docs.lakea.dev/start'

Environment is detected automatically:

• Browser on localhost → dev mode
• Otherwise → production mode

Usage

React/TypeScript

import { getAppLink } from '@lakea/core';

<a href={getAppLink('handbook')}>Docs</a>

Astro

---
import { getAppLink } from '@lakea/core';
---
<a href={getAppLink('handbook')}>Docs</a>

MDX (Handbook)

Use the AppLink component for cross-app links in MDX files:

---
# The import path depends on your file location
# From docs/architecture/: ../../../../components/AppLink.astro
# From docs/contributing/: ../../../../components/AppLink.astro
---
import AppLink from '../../../../components/AppLink.astro';

<AppLink app="exoplanet-catalog">View Catalog</AppLink>

Link Types

1. Internal links (within same app): Use relative paths

   [Getting Started](/contributing/getting-started)

2. Cross-app links: Use getAppLink() or <AppLink>

3. External links: Use full URLs

   [NASA Archive](https://exoplanetarchive.ipac.caltech.edu)

References

• App registry: packages/core/src/apps/index.ts
• Routing: packages/core/src/routing/index.ts