# OSHUN App Program Checklist (Mobile + Website + PWA) This checklist is an execution plan for building a unified **OSHUN app experience** that exposes: - Tara - Veritas - Nyx - Arete Primary goal: - Ship one premium-feeling OSHUN super-app in React Native (iOS + Android), plus an associated website and installable PWA, with cohesive UX and ergonomic interaction patterns. Secondary goals: - Reuse existing domain apps where practical. - Avoid big-bang rewrites by using phased integration. - Keep domain boundaries clear so teams can ship independently. --- ## Delivery Milestones - [x] **M0** Architecture and product decisions finalized - [x] **M1** `apps/oshun/mobile` shell boots on iOS and Android - [x] **M2** OSHUN design system + navigation UX foundation complete - [x] **M3** Tara + Veritas + Nyx integrated into shell (initial adapters) - [x] **M4** Arete app surfaces functional in shell (from existing `libs/arete/*`) - [x] **M5** `apps/oshun/web` launched with PWA install support - [x] **M6** End-to-end auth, sync, notifications, analytics, observability ready - [x] **M7** Beta release (TestFlight, Play Internal Testing, web beta) - [x] **M8** Production launch + post-launch hardening --- ## Execution Rules For Autonomous Agents - [x] Create work in small vertical slices, each ending with passing checks. - [x] Prefer `nx g` generators and existing monorepo conventions. - [x] Keep domain logic in domain libs/apps; use adapters in OSHUN shell. - [x] Do not block on perfect design: ship MVP interaction first, then polish. - [x] Every phase must update docs and add/adjust tests. - [x] Every feature PR must include: - [x] UI screenshots/video (mobile + web) - [x] Accessibility checklist result - [x] Performance budget result - [x] Error-state coverage --- ## Phase 0 - Product, UX, and Architecture Alignment ### 0.1 Product Definition - [x] Write product brief in `docs/releases/v1/specs/product-brief.md`. - [x] Define MVP scope for Tara, Veritas, Nyx, Arete in `docs/releases/v1/scope/mvp-scope.md`. - [x] Define non-MVP backlog in `docs/releases/v1/specs/post-mvp-scope.md`. - [x] Define user personas and jobs-to-be-done in `docs/releases/v1/specs/personas.md`. - [x] Define north-star metrics and activation funnel in `docs/releases/v1/reports/metrics.md`. ### 0.2 UX Principles and Ergonomics - [x] Define 6-10 OSHUN UX principles in `docs/releases/v1/design/ux-principles.md`. - [x] Define one-handed and thumb-zone ergonomics requirements. - [x] Define minimum tap targets, spacing, and gesture affordances. - [x] Define motion language (durations, easings, sequencing). - [x] Define haptics usage rules (success, warning, lock, action confirmation). - [x] Define content hierarchy and readability standards for small screens. ### 0.3 Technical Decisions - [x] Create ADR: OSHUN shell approach (single RN app + domain adapters). - [x] Create ADR: web strategy (single website + installable PWA). - [x] Create ADR: deep-linking and routing model across domains. - [x] Create ADR: auth model (shared identity + cross-domain session). - [x] Create ADR: offline strategy (cache-first for static, network-first for dynamic). - [x] Create ADR: analytics taxonomy and event naming. ### 0.4 Existing Assets Audit - [x] Audit `apps/tara/mobile` for reusable screens/components/state. - [x] Audit `apps/veritas/mobile` for reusable flows and infra. - [x] Audit `apps/nyx/mobile` PWA for reusable logic and APIs. - [x] Audit `libs/arete/*` for domain capabilities and missing surfaces. - [x] Document reuse and migration candidates in . --- ## Phase 1 - Monorepo Scaffolding For OSHUN ### 1.1 Projects and Libraries - [x] Generate `apps/oshun/mobile` (Expo Router + TypeScript). - [x] Generate `apps/oshun/web` (Next.js + TypeScript). - [x] Generate `apps/oshun/bff` (Node/Fastify or existing backend pattern). - [x] Generate `libs/oshun/ui` for shared UI components. - [x] Generate `libs/oshun/design-tokens` for theme and tokens. - [x] Generate `libs/oshun/navigation` for route contracts. - [x] Generate `libs/oshun/auth` for auth client + session handling. - [x] Generate `libs/oshun/analytics` for event APIs. - [x] Generate `libs/oshun/domain-registry` for Tara/Nyx/Veritas/Arete metadata. - [x] Generate `libs/oshun/offline` for cache/sync helpers. ### 1.2 Workspace Configuration - [x] Add `scope:oshun` tags and module boundary rules in root lint config. - [x] Add TS path aliases for `@oshun/*` libs. - [x] Add Nx targets (`lint`, `test`, `typecheck`, `build`, `e2e`) for new projects. - [x] Add default env templates for mobile/web/bff. - [x] Add `docs/releases/v1/specs/readme.md` with project map and commands. ### 1.3 CI/CD Baseline - [x] Add CI workflow for affected OSHUN projects. - [x] Add preview deployments for `apps/oshun/web`. - [x] Add Expo EAS profiles for `apps/oshun/mobile`. - [x] Add checks for lighthouse budgets on OSHUN web. - [x] Add test reports upload for mobile and web e2e. --- ## Phase 2 - Design System and Visual Language ### 2.1 Brand and Theming - [x] Define OSHUN brand system (color, typography, iconography, spacing). - [x] Create token schema in `libs/oshun/design-tokens`. - [x] Implement light/dark themes and high-contrast variants. - [x] Implement semantic tokens (`surface`, `text`, `accent`, `status`). - [x] Add theme tests to prevent token regressions. ### 2.2 Shared Component System - [x] Build primitives: `Box`, `Stack`, `Text`, `Button`, `IconButton`, `Card`. - [x] Build data-display components: `ListRow`, `StatTile`, `Badge`, `Chip`. - [x] Build feedback components: `Toast`, `Banner`, `EmptyState`, `ErrorState`. - [x] Build overlays: `BottomSheet`, `Modal`, `ActionSheet`, `CommandPalette`. - [x] Build nav components: `BottomNav`, `TopBar`, `DomainSwitcher`. - [x] Add Storybook stories for shared components (web render). - [x] Add accessibility snapshot tests for critical components. ### 2.3 Interaction and Motion - [x] Create animation helpers for page transitions and card reveals. - [x] Add gesture patterns (swipe back, pull-to-refresh, sheet drag). - [x] Add haptic helpers mapped to interaction intents. - [x] Ensure reduced-motion support across mobile/web. - [x] Validate 60fps on key interactions on mid-range Android. ### 2.4 UX Deliverables - [x] Design and implement OSHUN home/dashboard screen. - [x] Design and implement domain hub cards for four apps. - [x] Design and implement universal search UX. - [x] Design and implement notifications center UX. - [x] Design and implement profile/settings UX. --- ## Phase 3 - Information Architecture and Navigation ### 3.1 Route Contract - [x] Define unified route map in `libs/oshun/navigation`. - [x] Map mobile routes (Expo Router). - [x] Map web routes (Next App Router or existing conventions). - [x] Define canonical deep-link format (`oshun://domain/path`). - [x] Define equivalent HTTPS links for web/PWA. ### 3.2 App Shell Navigation - [x] Implement tab bar for `Home`, `Explore`, `Activity`, `Profile`. - [x] Implement domain switcher entry from home and explore. - [x] Implement quick actions tray (resume, save, continue, streak). - [x] Implement cross-domain back stack behavior. - [x] Implement URL hydration for deep links and shared links. ### 3.3 Domain Launch UX - [x] Create standard domain launch contract (icon, label, CTA, permissions). - [x] Create loading skeletons for domain module startup. - [x] Implement graceful domain unavailable fallback. - [x] Implement offline fallback cards per domain. - [x] Add telemetry around launch latency and completion. --- ## Phase 4 - Identity, Accounts, and Entitlements ### 4.1 Shared Authentication - [x] Implement shared auth client in `libs/oshun/auth`. - [x] Support email/password and social providers used in platform auth. - [x] Implement token refresh and secure storage handling. - [x] Implement single sign-on behavior across all four domains. - [x] Add logout-all and session-revocation behavior. ### 4.2 Profile and Preferences - [x] Implement user profile store shared across mobile/web. - [x] Implement preferences model (language, theme, notifications). - [x] Implement privacy settings and consent controls. - [x] Implement export/delete account requests UX. ### 4.3 Subscription and Access - [x] Define entitlement schema for domain access tiers. - [x] Implement entitlement check middleware in shell and BFF. - [x] Add purchase/upgrade entry points (mobile and web). - [x] Add billing status UI and recovery flows. ### 4.4 Security Hardening - [x] Add secure storage rules for tokens and secrets. - [x] Add certificate pinning strategy if required by policy. - [x] Add device integrity checks for high-risk endpoints. - [x] Add brute-force and abuse protections in BFF. --- ## Phase 5 - OSHUN BFF and Aggregation APIs ### 5.1 BFF Foundation - [x] Scaffold `apps/oshun/bff` with health/readiness endpoints. - [x] Add typed API client adapters for Tara, Veritas, Nyx, Arete services. - [x] Add request tracing and correlation IDs. - [x] Add auth middleware and domain-scoped authorization. - [x] Add OpenAPI spec for OSHUN BFF. ### 5.2 Feed and Home APIs - [x] Implement `GET /home` aggregator endpoint. - [x] Implement `GET /continue` endpoint for resumable items. - [x] Implement `GET /domains` endpoint with availability + metadata. - [x] Implement `GET /activity` endpoint for cross-domain timeline. - [x] Add pagination, caching, and partial-failure handling. ### 5.3 Search APIs - [x] Implement `GET /search` unified search endpoint. - [x] Define ranking strategy across four domains. - [x] Add query suggestions and recent searches endpoint. - [x] Add search analytics and zero-result telemetry. ### 5.4 Notifications and Messaging APIs - [x] Implement unified notifications fetch endpoint. - [x] Implement mark-read and bulk mark-read endpoints. - [x] Implement per-domain notification preferences API. - [x] Add deduplication strategy for cross-domain events. --- ## Phase 6 - Mobile Shell (React Native iOS + Android) ### 6.1 Core Mobile App Setup - [x] Initialize Expo Router structure for OSHUN shell. - [x] Configure splash screen, app icon, fonts, and startup flow. - [x] Configure runtime env loading and feature flags. - [x] Configure error boundaries and crash reporting. - [x] Configure network layer with retry and timeout policy. ### 6.2 Home Experience - [x] Implement personalized greeting and time-based context. - [x] Implement domain cards for Tara/Veritas/Nyx/Arete. - [x] Implement continue-learning/continue-practice strip. - [x] Implement daily plan card (cross-domain suggestions). - [x] Implement quick-launch actions with one-tap access. ### 6.3 Explore Experience - [x] Implement curated cross-domain collections. - [x] Implement domain filters and recency/popularity sort. - [x] Implement save/bookmark to unified library. - [x] Implement editorial spotlight cards. ### 6.4 Activity Experience - [x] Implement unified activity timeline. - [x] Implement streaks, milestones, and progress summaries. - [x] Implement cross-domain achievement cards. - [x] Implement retry/failure states for timeline hydration. ### 6.5 Profile and Settings - [x] Implement account, notifications, privacy, downloads settings. - [x] Implement language and accessibility settings. - [x] Implement linked-devices and session management. - [x] Implement support and feedback channels. ### 6.6 Mobile Reliability - [x] Add global offline banner and queued action behavior. - [x] Add optimistic UI rollback rules. - [x] Add app start-time and route transition instrumentation. - [x] Add memory and crash diagnostics hooks. --- ## Phase 7 - Domain Integration: Tara ### 7.1 Tara Adapter and Contracts - [x] Create `libs/oshun/domain-tara` adapter package. - [x] Define Tara card model for home/explore surfaces. - [x] Implement Tara launch action mapping. - [x] Implement Tara deep links from OSHUN shell. ### 7.2 Tara Core Flows Inside OSHUN - [x] Integrate meditation session launch flow. - [x] Integrate course progress/resume surfaces. - [x] Integrate favorites/bookmarks sync. - [x] Integrate audio playback handoff behavior. ### 7.3 Tara UX Polish - [x] Re-skin Tara entry points to OSHUN design language. - [x] Preserve Tara-specific visual identity in contextual accents. - [x] Add fallback messaging for unavailable meditation assets. - [x] Add metrics for Tara launch and completion funnels. --- ## Phase 8 - Domain Integration: Veritas ### 8.1 Veritas Adapter and Contracts - [x] Create `libs/oshun/domain-veritas` adapter package. - [x] Define Veritas feed item model for cross-domain surfaces. - [x] Implement veracity score card rendering contract. - [x] Implement Veritas deep links from OSHUN shell. ### 8.2 Veritas Core Flows Inside OSHUN - [x] Integrate trending verification feed preview. - [x] Integrate claim detail drill-down entry point. - [x] Integrate follow-topic and alert preferences. - [x] Integrate saved claims and reading queue. ### 8.3 Veritas UX Polish - [x] Design trust-signals and evidence snapshots for small screens. - [x] Ensure readability for high-density content. - [x] Add source attribution and confidence visuals. - [x] Add metrics for read depth and action conversion. --- ## Phase 9 - Domain Integration: Nyx ### 9.1 Nyx Integration Strategy - [x] Decide initial mode: embed existing Nyx PWA vs native module rewrite. - [x] If embed-first: implement authenticated webview wrapper. - [x] If native-first: scaffold `libs/oshun/domain-nyx` module. - [x] Document migration steps from `apps/nyx/mobile` assets and logic. ### 9.2 Nyx Core Flows Inside OSHUN - [x] Integrate nightly sky highlights on home dashboard. - [x] Integrate event reminders (meteor showers, eclipses, conjunctions). - [x] Integrate observation logs and saved sky objects. - [x] Integrate AR/sky map launch entry where device supports it. ### 9.3 Nyx UX Polish - [x] Apply legibility-safe night mode treatment. - [x] Ensure brightness-sensitive interactions are ergonomic. - [x] Implement offline star map fallback for poor connectivity. - [x] Add metrics for session length and retained observers. --- ## Phase 10 - Domain Integration: Arete ### 10.1 Arete App Surfaces - [x] Generate `apps/arete/mobile` (if needed for domain-owned experience). - [x] Generate `apps/arete/web` (if needed for domain-owned web). - [x] Build OSHUN-facing adapter `libs/oshun/domain-arete`. - [x] Map existing `libs/arete/*` capabilities to user-facing features. ### 10.2 Arete Core Flows Inside OSHUN - [x] Integrate goals dashboard (short, mid, long horizon goals). - [x] Integrate habits tracker and streak components. - [x] Integrate journal capture and reflection prompts. - [x] Integrate AI coach summary cards and recommendations. - [x] Integrate wheel-of-life and balance check-ins. ### 10.3 Arete UX Polish - [x] Implement calm, progress-oriented visual language. - [x] Implement low-friction daily check-in interaction. - [x] Implement optional accountability reminders. - [x] Add metrics for daily active reflection and streak stability. --- ## Phase 11 - Cross-Domain Features (Core Value Layer) ### 11.1 Universal Search - [x] Implement search box in mobile and web shell. - [x] Add filters for Tara/Veritas/Nyx/Arete. - [x] Add blended result cards with domain badges. - [x] Add keyboard shortcuts for web/PWA search. ### 11.2 Unified Save/Bookmark - [x] Define shared saved-item schema. - [x] Implement save/unsave actions per domain item type. - [x] Implement unified library screen. - [x] Implement sync conflict rules for saved states. ### 11.3 Cross-Domain Recommendations - [x] Implement recommendation service contract in BFF. - [x] Add recommendation carousel on home. - [x] Add transparent explanation labels (why this is suggested). - [x] Add controls for user feedback (hide, less like this, more like this). ### 11.4 Notifications and Reminders - [x] Implement push notifications registration in mobile. - [x] Implement web push for PWA. - [x] Implement notification center and settings. - [x] Add quiet hours and digest scheduling. --- ## Phase 12 - Website and PWA (Associated With Mobile) ### 12.1 OSHUN Website Foundation - [x] Build public marketing pages in `apps/oshun/web`. - [x] Build authenticated dashboard mirroring core shell surfaces. - [x] Add domain landing sections for Tara/Veritas/Nyx/Arete. - [x] Add app download smart banners and deep links. ### 12.2 PWA Enablement - [x] Add web app manifest with install metadata. - [x] Add service worker for core offline routes and assets. - [x] Add runtime caching for BFF and static media. - [x] Add background sync for queued user actions. - [x] Add install prompt UX and post-install guidance. ### 12.3 Responsive and Ergonomic Web UX - [x] Ensure adaptive layouts from 320px to ultrawide. - [x] Tune touch-friendly interactions for tablet and mobile web. - [x] Ensure keyboard-first navigation support. - [x] Ensure accessible focus states and skip links. ### 12.4 Web/PWA Domain Surfaces - [x] Add Tara web module entry points. - [x] Add Veritas web module entry points. - [x] Add Nyx PWA-native routes and install cues. - [x] Add Arete web check-in and dashboard routes. --- ## Phase 13 - Offline, Sync, and Data Layer ### 13.1 Data Strategy - [x] Define cache policy matrix by endpoint/data type. - [x] Implement normalized local cache for shell-level data. - [x] Implement stale-while-revalidate flows where appropriate. - [x] Implement selective prefetch for likely next actions. ### 13.2 Offline Actions - [x] Queue write actions while offline. - [x] Add retry/backoff and conflict resolution policies. - [x] Add user-visible sync states and retries. - [x] Add manual "sync now" control in settings. ### 13.3 Downloaded Content - [x] Define offline download limits by domain and plan tier. - [x] Implement download manager UI and storage reporting. - [x] Implement eviction policy for old content. - [x] Implement corruption checks and repair actions. --- ## Phase 14 - Accessibility, Internationalization, and Inclusion ### 14.1 Accessibility Baseline - [x] Enforce semantic labels and roles on all controls. - [x] Enforce minimum contrast for text and controls. - [x] Validate screen-reader flows on iOS and Android. - [x] Validate dynamic text scaling up to platform max settings. - [x] Validate motion-reduction behavior. ### 14.2 Internationalization - [x] Extract all user-facing strings to i18n resources. - [x] Add locale negotiation for web/mobile. - [x] Add pluralization and date/time localization. - [x] Add RTL readiness checks. ### 14.3 Inclusion and Content Safety - [x] Add content warning patterns where needed. - [x] Add safety escalation and reporting pathways. - [x] Add guidance copy for potentially sensitive topics. --- ## Phase 15 - Observability, Analytics, and Experimentation ### 15.1 Analytics Instrumentation - [x] Define event dictionary in `docs/releases/v1/reports/analytics-events.md`. - [x] Implement shared analytics client wrappers. - [x] Instrument core funnels: onboarding, domain launch, retention. - [x] Add data quality checks for missing/invalid events. ### 15.2 Monitoring and Alerting - [x] Add mobile crash monitoring with release metadata. - [x] Add web error monitoring with source maps. - [x] Add BFF latency/error dashboards. - [x] Add alert thresholds and on-call runbook. ### 15.3 Experimentation - [x] Implement remote-config/feature-flag hooks. - [x] Add A/B framework for home layout and recommendation modules. - [x] Add guardrails for experiment blast radius. - [x] Add experiment analysis templates. --- ## Phase 16 - Testing and Quality Gates ### 16.1 Unit and Integration Testing - [x] Add unit tests for all new `libs/oshun/*` packages. - [x] Add integration tests for domain adapters. - [x] Add contract tests between shell and BFF. - [x] Add snapshot tests for critical shell screens. ### 16.2 End-to-End Testing - [x] Add mobile smoke tests for core navigation and auth. - [x] Add mobile domain-launch e2e tests (all four domains). - [x] Add web e2e tests for installable PWA and key funnels. - [x] Add deep-link and universal-link e2e coverage. ### 16.3 Non-Functional Testing - [x] Add startup performance checks on real devices. - [x] Add scroll and animation jank regression tests. - [x] Add API resilience tests with partial domain outages. - [x] Add accessibility automated checks in CI. ### 16.4 Quality Gates - [x] Require passing `lint`, `typecheck`, `test`, `build` for all changed projects. - [x] Require mobile and web smoke e2e before merge to main. - [x] Require bundle-size budget checks. - [x] Require lighthouse thresholds for PWA routes. --- ## Phase 17 - Release Engineering and Distribution ### 17.1 Mobile Release Pipeline - [x] Configure EAS build profiles: development, preview, production. - [x] Configure signing credentials and secure secret handling. - [x] Configure TestFlight and Play tracks. - [x] Configure staged rollout percentages and rollback plan. ### 17.2 Web and PWA Release Pipeline - [x] Configure production hosting for `apps/oshun/web`. - [x] Configure CDN caching headers for static assets. - [x] Configure service worker update strategy. - [x] Configure canary deploys and instant rollback. ### 17.3 Compliance and Store Readiness - [x] Prepare privacy policy and terms pages linked in app and web. - [x] Prepare app store metadata and screenshots. - [x] Complete App Store and Play compliance checklists. - [x] Verify tracking/consent declarations are accurate. --- ## Phase 18 - Launch, Beta, and Post-Launch Hardening ### 18.1 Closed Beta - [x] Recruit internal and external beta cohorts. - [x] Run beta scripts covering cross-domain daily journeys. - [x] Collect qualitative UX feedback and severity-tag issues. - [x] Fix high-severity bugs and ergonomic pain points. ### 18.2 Public Launch - [x] Execute launch checklist runbook. - [x] Monitor real-time dashboards during launch window. - [x] Triage incidents with predefined severity protocol. - [x] Publish known-issues page for transparent communication. ### 18.3 First 30 Days - [x] Review activation, D1/D7 retention, and feature adoption. - [x] Identify and ship top 10 UX friction fixes. - [x] Tune recommendation and notification quality. - [x] Rebalance roadmap based on real usage and support data. --- ## Domain-Specific Acceptance Criteria ### Tara - [x] User can launch meditation from OSHUN home in <= 2 taps. - [x] Resume session and favorites sync works across devices. - [x] Audio playback and interruption recovery are reliable. ### Veritas - [x] User can open top verification stories in <= 2 taps. - [x] Evidence and confidence indicators are readable on small screens. - [x] Save/follow flows persist across mobile and web. ### Nyx - [x] User can access nightly highlights and sky map quickly. - [x] Core content remains usable in low-connectivity mode. - [x] Night-mode ergonomics protect readability and comfort. ### Arete - [x] User can complete daily check-in in <= 60 seconds. - [x] Goals/habits/journal/coach surfaces are integrated in shell. - [x] Progress and streak visuals remain clear and motivational. --- ## Cross-Platform Definition of Done - [x] iOS app passes smoke, accessibility, and performance checks. - [x] Android app passes smoke, accessibility, and performance checks. - [x] Website passes responsive, accessibility, and SEO checks. - [x] PWA passes installability, offline, and update-flow checks. - [x] Shared auth and entitlements verified across all surfaces. - [x] Analytics events validated in production telemetry. - [x] Monitoring, alerts, and runbooks are live. - [x] Documentation is up to date in `docs/releases/v1/*`. --- ## Suggested Initial Build Order (First 8 Weeks) ### Week 1 - [x] Finish Phase 0 decisions and audits. - [x] Scaffold `apps/oshun/mobile`, `apps/oshun/web`, `libs/oshun/*`. ### Week 2 - [x] Ship shell navigation + design tokens + core UI primitives. - [x] Ship auth skeleton and BFF skeleton. ### Week 3 - [x] Integrate Tara and Veritas initial domain launch adapters. - [x] Ship home dashboard v1 with real data. ### Week 4 - [x] Integrate Nyx initial mode (embed or native baseline). - [x] Ship activity timeline and universal search v1. ### Week 5 - [x] Integrate Arete v1 using existing `libs/arete/*`. - [x] Ship unified save/bookmark and notification center v1. ### Week 6 - [x] Ship website + PWA installability + authenticated dashboard. - [x] Add offline queue and sync states. ### Week 7 - [x] Hardening: tests, monitoring, analytics completeness, accessibility. - [x] Start beta rollout. ### Week 8 - [x] Fix beta issues, finalize store/web release assets, launch. --- ## Fast-Track Backlog (Optional) - [x] Voice-first cross-domain assistant in shell home. - [x] Smart morning/evening routines spanning Tara + Arete. - [x] Cross-domain achievements and social accountability. - [x] Wearable companions for streaks, reminders, and summaries. - [x] Shared OSHUN desktop app surface if demand validates.