Disciplines · Decisions (ADRs)

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

OSHUN requires a web presence that serves two roles:

Accepted · 2026-02-16
11sections5 minread
Markdown source
On this page

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
  • 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