Status: Accepted v1.0
Date: March 23, 2026
Owners: OSHUN Product, OSHUN Engineering, Domain Leads, Support/Ops
Related:
docs/releases/v1/specs/domain-service-consolidation-strategy.mddocs/releases/v1/scope/domain-service-routing-and-discovery-rules.mddocs/releases/v1/specs/program-charter.mddocs/releases/v1/specs/web-app-admin-v1-prd.mddocs/releases/v1/scope/mvp-scope.mddocs/releases/v1/specs/todos.md
1. Purpose#
This document defines when a standalone domain web or mobile frontend may be deprecated, redirected, delisted, or retired because the unified OSHUN shell now owns the overlapping user journey.
It exists to close V1-ARCH-086. The consolidation strategy already established
that standalone domain frontends are not canonical shell surfaces. What it did
not yet define was:
- how to distinguish a true shell-superseded frontend from a specialist product
- what evidence is required before a legacy web or mobile surface can be deprecated
- which current frontend trees are actual sunset candidates versus retained specialist surfaces
This document closes V1-ARCH-086. It does not close V1-ARCH-087 through
V1-ARCH-089.
2. Repo-Informed Current State#
The current repository shows all of the following:
apps/oshun/webandapps/oshun/mobileare the canonical unified customer shell surfaces.- standalone customer-facing or domain-native frontend trees still exist for Tara, Veritas, Nyx, Iris, Lilith, and Metis.
- Tara, Veritas, and Nyx each still have customer web/mobile or PWA frontends that overlap with shell-facing journeys.
- Nyx also has specialist immersive clients (
apps/nyx/star-map,apps/nyx/ar-sky,apps/nyx/vr-planetarium) whose modality is broader than the shell's current scope. - Iris, Lilith, and Metis include standalone desktop, admin, dashboard, or broader domain-native experiences that are not automatically superseded by a customer shell.
apps/iris/webis present as a directory in the tree but does not currently expose apackage.json, so it must be treated as inventory residue rather than an approved deployable frontend until separately clarified.
The governing problem is not "remove all standalone apps." The governing problem is deciding which overlapping frontends should stay as specialist products and which should be formally migrated into the shell.
3. Governing Decision#
For OSHUN V1, a standalone frontend may be sunset only when the shell is the approved canonical surface for the same user, same job-to-be-done, and same launch-critical journey class.
The following rules are mandatory:
- Customer-facing overlap is the only scope eligible for shell-driven sunset. Desktop, admin, dashboard, XR, operator, creator, enterprise, and substrate surfaces are not sunset candidates merely because the shell exists.
- A frontend is
superseded by the shellonly when OSHUN owns the relevant journey end to end through shell UX, shell routing, shell auth/session, and BFF-mediated backend contracts. - No standalone frontend may be deprecated on aesthetics or org preference alone. Deprecation requires verified journey parity, migration evidence, and support readiness.
- If a standalone frontend still provides a unique modality or specialist workflow that the shell does not intend to own, it remains a retained specialist surface rather than a sunset candidate.
- Standalone mobile surfaces require a stricter bar than web because store listings, installed versions, push permissions, and offline data make retirement harder to reverse safely.
4. Lifecycle States#
Every standalone frontend in scope must be assigned one of the following states:
| Lifecycle state | Meaning |
|---|---|
specialist-retained |
Product remains outside shell supersession scope and is not on a shell-driven retirement path. |
parallel-migration |
Frontend overlaps with the shell and may continue temporarily while shell parity and migration mature. |
redirect-ready |
Sunset gates are satisfied; traffic may be redirected or store delisting may begin after notice windows complete. |
sunset-approved |
Owners approved shutdown/delisting/retirement and rollback conditions are documented. |
retired |
Frontend is no longer a supported entry point; redirects, delisting, or archival controls are in place. |
inventory-residue |
Repo path exists but is not yet a clearly supported deployable product; classify before any sunset decision. |
State transitions are one-way except for rollback from redirect-ready or
sunset-approved back to parallel-migration when migration health degrades.
5. Minimum Sunset Gates#
All of the following must be true before a parallel-migration frontend can
move to redirect-ready.
5.1 Shared Gates for Web and Mobile#
- The overlapping journey set is written explicitly and approved by the domain lead and OSHUN product lead.
- OSHUN owns 100% of launch-blocking overlapping journeys and at least 95% of overlapping session volume from the most recent 28-day measurement window, unless an explicit written exception is approved.
- Shell flows for those journeys use canonical shell auth, deep links, BFF routing, save/progress state, notifications where applicable, and analytics.
- Data continuity is preserved for overlapping journeys: bookmarks, progress, preferences, entitlements, and recent activity cannot silently reset during migration.
- Relevant automation for the shell-owned replacement path is present and passing: lint, typecheck, affected tests, and browser/mobile end-to-end coverage for the migrated journeys.
- Migration telemetry exists for legacy entry, shell entry, redirect success, deep-link success, auth handoff, and critical failure states.
- No unresolved P0 or P1 defect remains on the shell replacement path and no unresolved legal, privacy, policy, or support blocker remains for the migrated journeys.
- Support, incident, and rollback runbooks are updated and on-call ownership is explicit.
5.2 Web-Specific Gates#
Before a standalone web surface can be redirected or retired:
- Legacy routes that map to shell-owned journeys have verified redirect destinations or explanatory landing pages.
- SEO, canonical metadata, and public-link behavior are updated so search and share traffic does not land on broken or contradictory surfaces.
- Anonymous and authenticated traffic both have deterministic handling for the redirect path.
- Web Playwright coverage verifies legacy-to-shell redirect behavior, authenticated handoff, and degraded-state behavior.
- A minimum 30-day notice window has been provided unless the web surface was internal-only or never publicly launched.
5.3 Mobile-Specific Gates#
Before a standalone mobile app can be delisted or retired:
- Universal Links, App Links, and in-app deep links route users into the shell for all superseded journeys.
- Push-notification destinations, notification preferences, and permission state are migrated or intentionally reset with explicit user communication.
- Offline or downloaded assets required by the overlapping journeys have a shell replacement strategy or an approved exception.
- Mobile end-to-end automation verifies notification routing, auth/session continuity, reinstall/upgrade behavior, and offline/retry behavior where the legacy app previously supported them.
- At least one released legacy-app version contains the deprecation notice and shell migration path before store delisting.
- A minimum 45-day notice window has elapsed between first in-app deprecation notice and store delisting, unless the app never reached public launch.
6. Sunset Approval Packet#
No frontend may move from redirect-ready to sunset-approved until a written
approval packet exists containing all of the following:
- scoped journey map showing what is superseded and what remains out of scope
- telemetry summary for the overlap period
- support and incident rollback plan
- redirect or delisting execution date
- customer communication plan
- owner signoff from domain lead, OSHUN product, engineering, and support/ops
7. Current Frontend Classification#
The table below is the canonical March 23, 2026 classification for the standalone domain frontend trees currently visible in this repository.
| Frontend path | Current lifecycle state | Shell supersession posture | Reasoning |
|---|---|---|---|
apps/tara/web |
parallel-migration |
sunset candidate for overlapping customer meditation journeys | Tara README explicitly says OSHUN exposes only the highest-value Tara entry points today, so retirement is possible only after parity on those journeys. |
apps/tara/mobile |
parallel-migration |
sunset candidate for overlapping customer meditation journeys | Mobile overlap exists, but offline audio, continuity, and mobile notification migration must be proven before delisting. |
apps/veritas/web |
parallel-migration |
sunset candidate for overlapping customer reading and claim-inspection journeys | Veritas shell scope is intentionally narrower than the full newsroom platform, so only overlapping shell-owned user journeys are sunsetable. |
apps/veritas/mobile |
parallel-migration |
sunset candidate for overlapping customer reading and alert journeys | Same posture as web, with extra mobile gating for notifications, saved state, and install-base migration. |
apps/nyx/mobile |
parallel-migration |
sunset candidate only for shell-owned nightly-highlight and continuity journeys | MVP docs still allow Nyx to remain an explicit module; sunset depends on shell/mobile parity for saved objects, reminders, and deep-link continuity. |
apps/nyx/star-map |
specialist-retained |
not superseded by default | Star-map is a specialist immersive/observatory surface, not a generic shell replacement target. |
apps/nyx/ar-sky |
specialist-retained |
not superseded by default | AR modality is a domain-native specialist experience outside current shell supersession scope. |
apps/nyx/vr-planetarium |
specialist-retained |
not superseded by default | VR modality is a specialist experience and remains independent unless a separate accepted retirement plan exists. |
apps/iris/dashboard |
specialist-retained |
not a customer-shell sunset candidate | Iris is a substrate platform with dashboard/operator concerns broader than shell customer journeys. |
apps/iris/web |
inventory-residue |
classify separately before any retirement decision | Repo path exists without a package.json, so it is not currently treated as a verified deployable standalone frontend. |
apps/iris/mobile |
specialist-retained |
not a customer-shell sunset candidate | Iris mobile is part of a broader assistant platform across device classes, not just a shell-overlap surface. |
apps/iris/desktop |
specialist-retained |
not a customer-shell sunset candidate | Desktop is out of scope for shell-driven customer web/mobile retirement. |
apps/lilith/web |
specialist-retained |
not a customer-shell sunset candidate | Lilith remains a broader consciousness-experience platform whose standalone UI is not replaced merely by OSHUN customer shell parity. |
apps/lilith/mobile |
specialist-retained |
not a customer-shell sunset candidate | Same posture as Lilith web, with additional modality and device-capability scope outside shell overlap. |
apps/lilith/desktop |
specialist-retained |
not a customer-shell sunset candidate | Desktop is outside the web/mobile supersession problem. |
apps/metis/web |
parallel-migration |
potential sunset candidate for learner-facing shell-owned journeys only | Metis web overlaps future shell learning journeys, but the charter and Metis audit show shell integration is still incomplete. |
apps/metis/admin |
specialist-retained |
not a customer-shell sunset candidate | Admin surfaces belong to the canonical operator model, not the customer shell. Retire only if Oshun admin fully absorbs them. |
8. Domain-Specific Interpretation Rules#
8.1 Tara#
Tara web/mobile may be sunset only for the journeys OSHUN explicitly intends to own:
- launch session
- resume session
- save/favorite
- course progress summary
- session-audio continuity
Full Tara wellness-product breadth is not a prerequisite for OSHUN, but any overlapping Tara journey that remains critical and unsupported in shell blocks sunset.
8.2 Veritas#
Veritas web/mobile may be sunset only for shell-owned reading journeys such as:
- trending feed entry
- claim inspection
- continue reading
- save/follow behavior
- alert and notification continuity for shell-owned reading flows
Newsroom operations, regional media tooling, monetization, and broader editorial systems are not customer-shell sunset targets.
8.3 Nyx#
Only the shell-owned Nyx continuity layer is sunset-eligible:
- nightly highlights
- shell-owned event discovery
- saved objects
- reminder continuity
- shell-routed exploration entry
Immersive observatory clients remain specialist unless a separate shell product decision explicitly absorbs them.
8.4 Iris and Lilith#
Iris and Lilith are substrate or broader domain-native products. Their current standalone UIs are not subject to shell-driven deprecation unless OSHUN later defines a specific overlapping customer journey set and explicitly accepts the migration cost.
8.5 Metis#
Metis learner-facing web journeys may become sunset candidates once the shell and BFF-backed Metis adapter own those journeys end to end. Metis admin is not part of this customer-shell sunset policy; it belongs to the operator-surface convergence problem defined by the charter and admin PRD.
9. Acceptance Record#
The OSHUN V1 program accepts the following sunset policy:
- only overlapping customer web/mobile journeys are eligible for shell-driven retirement
- specialist, desktop, immersive, admin, and substrate frontends are retained unless a separate supersession decision exists
- sunset requires measurable parity, migration evidence, automation, support readiness, and notice windows
- Tara, Veritas, Nyx mobile, and Metis web are the current
parallel-migrationsurfaces; the rest are retained specialist surfaces or inventory residue
This acceptance closes V1-ARCH-086.