ADR 0002: Dashboard route composition (Option B)

ADR 0002: Dashboard route composition (Option B)

Status

Superseded (2026-04-24)

Context

This ADR recorded an intermediate route-composition approach during feature-package extraction. The current canonical model keeps dashboard UI composition app-owned.

TanStack Router’s file-based plugin generates routeTree.gen.ts from route modules. A route file that only re-exports Route from another module is not treated as a route definition, so the route can disappear from the tree and production breaks silently.

Decision

1. Route anchor stays in src/routes/**: Each dashboard route file continues to call createFileRoute(...) and export Route so codegen and types stay correct.
2. Feature package owns options: Loader, beforeLoad, component, search validation, and page UI can live in a feature package, with the route file passing those options into createFileRoute.
3. Stable route ids for getRouteApi: The feature package uses getRouteApi with the same path id the file route would have used (e.g. "/{-$locale}/(dashboard)/works/"), so hooks do not depend on Route from the re-export-only pattern.

Consequences

• One small indirection per extracted route (thin file in src/routes, fat options in package).
• No need to replace the entire route tree with a programmatic tree for the first migrations.
• Vite must resolve @host/* to the app src/ tree when bundling package sources (see vite.config.ts).

Superseded by

• docs/architecture/07-feature-source-of-truth.md (app-owned UI model)
• docs/architecture/17-feature-package-audit.md (current package ownership)

Alternatives considered

• Re-export-only route files: Rejected; router codegen skips them.
• Fully programmatic (dashboard) subtree: Higher risk and more churn; reserved if file-based limits block future routes.