# ADR-004: Domain Surface Architecture

**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`:

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

### Navigation Context

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
