# ADR-0008: OSHUN Web Strategy - Single Website with Installable PWA

**Status**: Accepted **Date**: 2026-02-16 **Authors**: OSHUN Web Engineering,
OSHUN Product Design, OSHUN Platform Engineering **Reviewers**: Domain Web Leads
(Tara, Veritas, Nyx, Arete) **Supersedes**: N/A **Superseded by**: N/A

## Context and Problem Statement

OSHUN requires a web presence that serves two roles:

- public website for discovery and conversion
- authenticated cross-domain shell mirroring mobile core journeys

The solution must also be installable as a PWA with reliable offline behavior
for core routes.

Current implementation patterns in this repository show:

- `apps/tara/web` is Next.js-based, has a manifest, custom service worker, and
  offline route.
- `apps/veritas/web` is Next.js-based, has a manifest, custom service worker,
  and richer offline reading infrastructure.
- `apps/nyx/mobile` is Vite-based and uses `vite-plugin-pwa` with auto-update
  and runtime caching.

We need one explicit OSHUN web strategy that avoids fragmented user journeys and
prevents domain-by-domain web silos from becoming the primary shell.

## Decision Drivers

- **One-product UX**: one URL and one coherent navigation model for OSHUN.
- **Installability**: reliable PWA install path and update behavior.
- **Cross-domain continuity**: shared auth/session/search/save/activity.
- **Delivery speed**: reuse proven Next.js + service worker patterns in-repo.
- **SEO + growth**: marketing routes and domain landing pages under one brand.
- **Operational simplicity**: single deployment artifact for shell web.
- **Resilience**: predictable offline fallback for key routes.

## Considered Options

### Option 1: Keep Separate Domain Websites Only

**Description**: keep Tara/Veritas/Nyx/Arete web properties independent and
avoid building a dedicated OSHUN shell website.

**Pros**:

- ✅ Lowest immediate platform integration effort
- ✅ Domain teams keep maximum autonomy
- ✅ No central shell web ownership required

**Cons**:

- ❌ Breaks OSHUN one-product promise on web
- ❌ Fragmented auth/session and inconsistent analytics taxonomy
- ❌ Duplicated conversion funnels and weak cross-domain discovery
- ❌ No canonical installable OSHUN PWA

### Option 2: Multi-Zone Web Architecture (Multiple Apps Behind One Domain)

**Description**: route `/tara`, `/veritas`, `/nyx`, `/arete` to separate
deployed apps behind an edge gateway.

**Pros**:

- ✅ Preserves domain app independence
- ✅ Reuse existing domain web apps with lower rewrite effort
- ✅ Incremental migration possible

**Cons**:

- ❌ Complex auth/session cohesion across zones
- ❌ Inconsistent navigation/performance/accessibility quality bars
- ❌ Harder PWA install/update semantics across multiple app zones
- ❌ Higher infrastructure and operational complexity

### Option 3: Single Next.js OSHUN Website + Installable PWA (Chosen)

**Description**: build one `apps/oshun/web` application (Next.js App Router)
that includes marketing and authenticated shell routes, with one PWA manifest
and one service worker strategy.

**Pros**:

- ✅ Delivers one coherent web shell aligned with mobile IA
- ✅ Centralized auth, analytics, accessibility, and design system
- ✅ Straightforward PWA install/update flow
- ✅ Unified SEO and growth funnel under OSHUN brand
- ✅ Operationally simpler than multi-zone shell

**Cons**:

- ❌ Requires shell-level web ownership and governance
- ❌ Requires adapter effort to surface domain content consistently
- ❌ Domain teams must align with shared route/system contracts

## Decision Outcome

**Chosen option**: Option 3 - one `apps/oshun/web` with first-class PWA support.

### Architecture Decision

OSHUN web will be implemented as:

- A single Next.js application in `apps/oshun/web`.
- Route structure that serves both:
  - public marketing pages
  - authenticated shell experiences (`Home`, `Explore`, `Activity`, `Profile`).
- Domain sections exposed as shell surfaces, not standalone shell substitutes.
- One web manifest and one service worker lifecycle for install/update/offline.

### Routing Model (Web Surface)

- Public routes:
  - `/`
  - `/tara`
  - `/veritas`
  - `/nyx`
  - `/arete`
  - `/download`
- Authenticated shell routes:
  - `/app/home`
  - `/app/explore`
  - `/app/activity`
  - `/app/profile`
  - `/app/search`
  - `/app/library`

Locale-prefixed variants are supported via i18n middleware conventions.

### PWA Strategy (Normative)

- Provide `manifest.webmanifest` (or `manifest.json`) with:
  - standalone display mode
  - maskable icons
  - shortcuts for high-value quick actions
- Register one service worker from shell root layout.
- Support update detection and explicit user refresh action when a new version
  is ready.
- Maintain offline fallback page for uncached navigation requests.

### Caching Strategy (Normative)

- App shell static assets: `CacheFirst` with immutable versioning.
- Navigation documents for shell routes: `NetworkFirst` with offline fallback.
- BFF/API data: `NetworkFirst` with short TTL cache and stale fallback.
- Media and images: `StaleWhileRevalidate` or `CacheFirst` with entry caps.
- Do not cache authenticated sensitive responses beyond defined policy limits.

### Installation and Update UX

- Trigger install prompt using `beforeinstallprompt` heuristics where supported.
- Provide explicit install CTA in web shell and marketing pages.
- After install, show first-run guidance for notifications/offline capabilities.
- On SW update, show non-blocking in-app banner with `Update now` action.

### Domain Integration Rules

- Domain content appears through shell adapters and contracts.
- Domain-specific web pages may continue to exist, but OSHUN web remains the
  canonical cross-domain shell entry point.
- Cross-domain search/save/activity are shell-owned and must not fork by domain.

## Implementation Plan

### Phase 1: Foundation

- Generate `apps/oshun/web` with Next.js + TypeScript.
- Add manifest, icons, service worker registration path, and offline route.
- Establish i18n and route middleware exclusions for SW/manifest files.

### Phase 2: Shell Surfaces

- Implement public marketing and authenticated shell route groups.
- Implement shared navigation and domain hub cards.
- Integrate auth/session and baseline analytics.

### Phase 3: PWA Hardening

- Add runtime caching rules for shell/API/media.
- Add install prompt UX and update banner flow.
- Add offline fallback and background sync hooks for queued actions.

### Phase 4: Verification

- Validate installability and update behavior on Chrome/Edge/Safari-supported
  contexts.
- Enforce Lighthouse thresholds for key shell routes.
- Validate accessibility and responsive coverage from `320px` upward.

## Success Metrics

- PWA install prompt acceptance rate meets product target for eligible sessions.
- PWA installability audits pass on production builds.
- Offline fallback success rate for supported routes >= 99% in simulated
  outages.
- Web route parity achieved for core shell journeys (`home`, `explore`,
  `activity`, `profile`).
- No domain-specific route can bypass shell auth/session policy.

## Consequences

### Positive Consequences

- ✅ One canonical OSHUN web identity and growth funnel.
- ✅ One PWA lifecycle model (manifest, SW, updates).
- ✅ Consistent interaction and accessibility quality bar across domains.
- ✅ Simpler observability and release governance for shell web.

### Negative Consequences

- ❌ Shell team carries central integration burden.
- ❌ Domain teams must align to shared contracts and route governance.
- ❌ Requires careful versioning to avoid SW cache regressions.

### Risks and Mitigations

| Risk                                          | Probability | Impact | Mitigation                                                      |
| --------------------------------------------- | ----------- | ------ | --------------------------------------------------------------- |
| Service worker update regressions             | Medium      | High   | Use staged rollout + explicit update banner + rollback playbook |
| Offline cache bloat hurts low-storage devices | Medium      | Medium | Enforce cache size caps and eviction policy by resource type    |
| Domain teams bypass shell routes for speed    | Medium      | Medium | Enforce shell entry requirements and shared KPI ownership       |
| i18n routing conflicts with SW/manifest paths | Low         | Medium | Maintain middleware exclusions for SW/manifest/workbox files    |

## Compliance and Security

- Service worker must not cache sensitive authenticated responses without policy
  review.
- Authenticated API caching must respect user/session boundaries.
- PWA install and push permission prompts must align with consent settings.

## Monitoring and Observability

Track:

- install prompt shown/accepted/dismissed events
- SW registration success/failure and update availability
- cache hit ratio by resource class
- offline fallback activations
- shell route web vitals and lighthouse scores

## Related Decisions

- `docs/adr/ADR-0013-oshun-shell-architecture-and-domain-adapters.md`
- Upcoming ADRs: deep-linking/routing, auth, offline strategy, analytics
  taxonomy

## References

- `apps/tara/web/next.config.js`
- `apps/tara/web/public/sw.js`
- `apps/veritas/web/next.config.mjs`
- `apps/veritas/web/public/sw.js`
- `apps/veritas/web/src/middleware.ts`
- `apps/nyx/mobile/vite.config.ts`