Status: Accepted Date: 2026-02-21
Context#
OSHUN is a multi-domain platform where each domain (Tara, Veritas, Nyx, Arete) represents a distinct product vertical with its own views, data, and user experience. We needed an architecture that isolates domains while sharing navigation and infrastructure.
Decision#
We use a domain surface pattern where each domain is a self-contained React component loaded via code splitting.
Domain Surfaces#
Each domain has a single top-level "surface" component that manages all of its views internally:
src/components/domains/
├── TaraSurface.tsx # All Tara views
├── VeritasSurface.tsx # All Veritas views
├── NyxSurface.tsx # All Nyx views
├── AreteSurface.tsx # All Arete views
├── tara/ # Tara sub-components
├── veritas/ # Veritas sub-components
├── nyx/ # Nyx sub-components
└── arete/ # Arete sub-components
Code Splitting#
Surfaces are loaded with React.lazy() in DomainRouteExperience.tsx:
const TaraSurface = lazy(() =>
import('./domains/TaraSurface').then((m) => ({ default: m.TaraSurface }))
);
A <Suspense fallback={<DomainSurfaceSkeleton />}> wraps the router.
Routing#
Two URL patterns route to domain surfaces:
- Domain-first:
/domains/:domainId— the primary navigation path - Canonical:
/d/:domainId— clean URLs for sharing
Both resolve to the same DomainRouteExperience component.
Internal View Routing#
Each surface manages its own view stack with useState:
const [view, setView] = useState<TaraView>('home');
// Views: 'home' | 'library' | 'breathwork' | 'courses' | ...
Deep linking is supported via the hydratedPath prop, which maps URL path
segments to internal views.
Navigation Context#
Cross-domain navigation preserves context via a back-stack:
interface WebDomainBackStackContext {
origin: WebShellRoute; // Where the user came from
stack: WebDomainId[]; // Breadcrumb of visited domains
}
Domain State Persistence#
saveDomainNavState() preserves scroll position and active path per domain, so
returning to a domain restores the user's previous position.
Rationale#
Why single surface components instead of Next.js page routes?#
- Domains need their own internal navigation that doesn't map cleanly to file- system routing
- Internal view transitions can be animated without full page navigations
- Domain state (scroll position, view stack) persists across tab switches
- Code splitting at the domain level provides the right granularity
Why React.lazy() instead of Next.js dynamic imports?#
React.lazy()withSuspensegives direct control over loading states- Domain surfaces use named exports, which
next/dynamichandles less elegantly - Skeleton fallbacks are domain-aware
Why internal view state instead of URL routing?#
- View transitions within a domain are fast (no network round-trip)
- URL still reflects the domain via
hydratedPathfor deep linking - View state resets naturally when leaving and returning to a domain
Consequences#
- Each domain surface is a large component that could be further decomposed
- Internal view routing isn't visible in Next.js navigation (no back/forward for sub-views within a domain)
- Adding a new domain requires creating a surface component, adding a case to the router switch, and registering in the domain registry
- Domain isolation means domains can't easily share UI state (by design)
- Back-stack management adds complexity but enables fluid cross-domain navigation