ADR 002: Subdomain Architecture
Status
Section titled “Status”Accepted (revised)
Context
Section titled “Context”Lakea consists of multiple applications that need to be accessible under a unified brand:
- Portal (main entry)
- Handbook (documentation)
- Exoplanet Catalog (data visualization)
- Future apps…
We initially considered path-based routing (lakea.dev/docs, lakea.dev/exoplanet-catalog) with a proxy, but this added complexity:
- Required a dev proxy for local testing
- Required an edge proxy (Cloudflare Worker) for production
- Base path configuration broke direct dev access
- Complex routing logic needed
Decision
Section titled “Decision”Use subdomains instead of path-based routing.
| App | Local | Production |
|---|---|---|
| Portal | localhost:4320 | lakea.dev |
| Handbook | localhost:4322 | docs.lakea.dev |
| Exoplanet Catalog | localhost:4321 | exoplanet.lakea.dev |
Each app is a separate Cloudflare Pages project with its own custom domain.
Consequences
Section titled “Consequences”Positive
Section titled “Positive”- Simpler deployment: Each app deploys independently to its own Pages project
- No proxy needed: No dev proxy, no edge proxy, no Workers
- Direct dev access works: Apps run on their own port with no path conflicts
- Free: Cloudflare Pages allows unlimited custom domains on free tier
- Independent scaling: Each app can have its own caching, redirects, etc.
Negative
Section titled “Negative”- DNS setup required: Need to configure subdomains in Cloudflare DNS
- Cross-origin in dev: Links between apps open in new context (different ports)
- Cookie sharing: Requires explicit configuration if needed (not currently needed)
Neutral
Section titled “Neutral”- Cross-app links use
getAppLink()which returns full URLs
Implementation
Section titled “Implementation”- Create separate Cloudflare Pages projects for each app
- Configure custom domains in Cloudflare DNS:
lakea.dev→ portal Pages projectdocs.lakea.dev→ handbook Pages projectexoplanet.lakea.dev→ exoplanet-catalog Pages project