Eve library

ADR-004: Domain Surface Architecture

ADR

Revision 1

On this page

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:

text
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:

typescript
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:

  1. Domain-first: /domains/:domainId — the primary navigation path
  2. 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:

typescript
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.

Cross-domain navigation preserves context via a back-stack:

typescript
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() with Suspense gives direct control over loading states
  • Domain surfaces use named exports, which next/dynamic handles 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 hydratedPath for 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