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#

• M0 Architecture and product decisions finalized
• M1 apps/oshun/mobile shell boots on iOS and Android
• M2 OSHUN design system + navigation UX foundation complete
• M3 Tara + Veritas + Nyx integrated into shell (initial adapters)
• M4 Arete app surfaces functional in shell (from existing libs/arete/*)
• M5 apps/oshun/web launched with PWA install support
• M6 End-to-end auth, sync, notifications, analytics, observability ready
• M7 Beta release (TestFlight, Play Internal Testing, web beta)
• M8 Production launch + post-launch hardening

Execution Rules For Autonomous Agents#

• Create work in small vertical slices, each ending with passing checks.
• Prefer nx g generators and existing monorepo conventions.
• Keep domain logic in domain libs/apps; use adapters in OSHUN shell.
• Do not block on perfect design: ship MVP interaction first, then polish.
• Every phase must update docs and add/adjust tests.
• Every feature PR must include:
  • UI screenshots/video (mobile + web)
  • Accessibility checklist result
  • Performance budget result
  • Error-state coverage

Phase 0 - Product, UX, and Architecture Alignment#

0.1 Product Definition#

• Write product brief in docs/releases/v1/specs/product-brief.md.
• Define MVP scope for Tara, Veritas, Nyx, Arete in docs/releases/v1/scope/mvp-scope.md.
• Define non-MVP backlog in docs/releases/v1/specs/post-mvp-scope.md.
• Define user personas and jobs-to-be-done in docs/releases/v1/specs/personas.md.
• Define north-star metrics and activation funnel in docs/releases/v1/reports/metrics.md.

0.2 UX Principles and Ergonomics#

• Define 6-10 OSHUN UX principles in docs/releases/v1/design/ux-principles.md.
• Define one-handed and thumb-zone ergonomics requirements.
• Define minimum tap targets, spacing, and gesture affordances.
• Define motion language (durations, easings, sequencing).
• Define haptics usage rules (success, warning, lock, action confirmation).
• Define content hierarchy and readability standards for small screens.

0.3 Technical Decisions#

• Create ADR: OSHUN shell approach (single RN app + domain adapters).
• Create ADR: web strategy (single website + installable PWA).
• Create ADR: deep-linking and routing model across domains.
• Create ADR: auth model (shared identity + cross-domain session).
• Create ADR: offline strategy (cache-first for static, network-first for dynamic).
• Create ADR: analytics taxonomy and event naming.

0.4 Existing Assets Audit#

• Audit apps/tara/mobile for reusable screens/components/state.
• Audit apps/veritas/mobile for reusable flows and infra.
• Audit apps/nyx/mobile PWA for reusable logic and APIs.
• Audit libs/arete/* for domain capabilities and missing surfaces.
• Document reuse and migration candidates in .

Phase 1 - Monorepo Scaffolding For OSHUN#

1.1 Projects and Libraries#

• Generate apps/oshun/mobile (Expo Router + TypeScript).
• Generate apps/oshun/web (Next.js + TypeScript).
• Generate apps/oshun/bff (Node/Fastify or existing backend pattern).
• Generate libs/oshun/ui for shared UI components.
• Generate libs/oshun/design-tokens for theme and tokens.
• Generate libs/oshun/navigation for route contracts.
• Generate libs/oshun/auth for auth client + session handling.
• Generate libs/oshun/analytics for event APIs.
• Generate libs/oshun/domain-registry for Tara/Nyx/Veritas/Arete metadata.
• Generate libs/oshun/offline for cache/sync helpers.

1.2 Workspace Configuration#

• Add scope:oshun tags and module boundary rules in root lint config.
• Add TS path aliases for @oshun/* libs.
• Add Nx targets (lint, test, typecheck, build, e2e) for new projects.
• Add default env templates for mobile/web/bff.
• Add docs/releases/v1/specs/readme.md with project map and commands.

1.3 CI/CD Baseline#

• Add CI workflow for affected OSHUN projects.
• Add preview deployments for apps/oshun/web.
• Add Expo EAS profiles for apps/oshun/mobile.
• Add checks for lighthouse budgets on OSHUN web.
• Add test reports upload for mobile and web e2e.

Phase 2 - Design System and Visual Language#

2.1 Brand and Theming#

• Define OSHUN brand system (color, typography, iconography, spacing).
• Create token schema in libs/oshun/design-tokens.
• Implement light/dark themes and high-contrast variants.
• Implement semantic tokens (surface, text, accent, status).
• Add theme tests to prevent token regressions.

2.2 Shared Component System#

• Build primitives: Box, Stack, Text, Button, IconButton, Card.
• Build data-display components: ListRow, StatTile, Badge, Chip.
• Build feedback components: Toast, Banner, EmptyState, ErrorState.
• Build overlays: BottomSheet, Modal, ActionSheet, CommandPalette.
• Build nav components: BottomNav, TopBar, DomainSwitcher.
• Add Storybook stories for shared components (web render).
• Add accessibility snapshot tests for critical components.

2.3 Interaction and Motion#

• Create animation helpers for page transitions and card reveals.
• Add gesture patterns (swipe back, pull-to-refresh, sheet drag).
• Add haptic helpers mapped to interaction intents.
• Ensure reduced-motion support across mobile/web.
• Validate 60fps on key interactions on mid-range Android.

2.4 UX Deliverables#

• Design and implement OSHUN home/dashboard screen.
• Design and implement domain hub cards for four apps.
• Design and implement universal search UX.
• Design and implement notifications center UX.
• Design and implement profile/settings UX.

Phase 3 - Information Architecture and Navigation#

3.1 Route Contract#

• Define unified route map in libs/oshun/navigation.
• Map mobile routes (Expo Router).
• Map web routes (Next App Router or existing conventions).
• Define canonical deep-link format (oshun://domain/path).
• Define equivalent HTTPS links for web/PWA.

3.2 App Shell Navigation#

• Implement tab bar for Home, Explore, Activity, Profile.
• Implement domain switcher entry from home and explore.
• Implement quick actions tray (resume, save, continue, streak).
• Implement cross-domain back stack behavior.
• Implement URL hydration for deep links and shared links.

3.3 Domain Launch UX#

• Create standard domain launch contract (icon, label, CTA, permissions).
• Create loading skeletons for domain module startup.
• Implement graceful domain unavailable fallback.
• Implement offline fallback cards per domain.
• Add telemetry around launch latency and completion.

Phase 4 - Identity, Accounts, and Entitlements#

4.1 Shared Authentication#

• Implement shared auth client in libs/oshun/auth.
• Support email/password and social providers used in platform auth.
• Implement token refresh and secure storage handling.
• Implement single sign-on behavior across all four domains.
• Add logout-all and session-revocation behavior.

4.2 Profile and Preferences#

• Implement user profile store shared across mobile/web.
• Implement preferences model (language, theme, notifications).
• Implement privacy settings and consent controls.
• Implement export/delete account requests UX.

4.3 Subscription and Access#

• Define entitlement schema for domain access tiers.
• Implement entitlement check middleware in shell and BFF.
• Add purchase/upgrade entry points (mobile and web).
• Add billing status UI and recovery flows.

4.4 Security Hardening#

• Add secure storage rules for tokens and secrets.
• Add certificate pinning strategy if required by policy.
• Add device integrity checks for high-risk endpoints.
• Add brute-force and abuse protections in BFF.

Phase 5 - OSHUN BFF and Aggregation APIs#

5.1 BFF Foundation#

• Scaffold apps/oshun/bff with health/readiness endpoints.
• Add typed API client adapters for Tara, Veritas, Nyx, Arete services.
• Add request tracing and correlation IDs.
• Add auth middleware and domain-scoped authorization.
• Add OpenAPI spec for OSHUN BFF.

5.2 Feed and Home APIs#

• Implement GET /home aggregator endpoint.
• Implement GET /continue endpoint for resumable items.
• Implement GET /domains endpoint with availability + metadata.
• Implement GET /activity endpoint for cross-domain timeline.
• Add pagination, caching, and partial-failure handling.

5.3 Search APIs#

• Implement GET /search unified search endpoint.
• Define ranking strategy across four domains.
• Add query suggestions and recent searches endpoint.
• Add search analytics and zero-result telemetry.

5.4 Notifications and Messaging APIs#

• Implement unified notifications fetch endpoint.
• Implement mark-read and bulk mark-read endpoints.
• Implement per-domain notification preferences API.
• Add deduplication strategy for cross-domain events.

Phase 6 - Mobile Shell (React Native iOS + Android)#

6.1 Core Mobile App Setup#

• Initialize Expo Router structure for OSHUN shell.
• Configure splash screen, app icon, fonts, and startup flow.
• Configure runtime env loading and feature flags.
• Configure error boundaries and crash reporting.
• Configure network layer with retry and timeout policy.

6.2 Home Experience#

• Implement personalized greeting and time-based context.
• Implement domain cards for Tara/Veritas/Nyx/Arete.
• Implement continue-learning/continue-practice strip.
• Implement daily plan card (cross-domain suggestions).
• Implement quick-launch actions with one-tap access.

6.3 Explore Experience#

• Implement curated cross-domain collections.
• Implement domain filters and recency/popularity sort.
• Implement save/bookmark to unified library.
• Implement editorial spotlight cards.

6.4 Activity Experience#

• Implement unified activity timeline.
• Implement streaks, milestones, and progress summaries.
• Implement cross-domain achievement cards.
• Implement retry/failure states for timeline hydration.

6.5 Profile and Settings#

• Implement account, notifications, privacy, downloads settings.
• Implement language and accessibility settings.
• Implement linked-devices and session management.
• Implement support and feedback channels.

6.6 Mobile Reliability#

• Add global offline banner and queued action behavior.
• Add optimistic UI rollback rules.
• Add app start-time and route transition instrumentation.
• Add memory and crash diagnostics hooks.

Phase 7 - Domain Integration: Tara#

7.1 Tara Adapter and Contracts#

• Create libs/oshun/domain-tara adapter package.
• Define Tara card model for home/explore surfaces.
• Implement Tara launch action mapping.
• Implement Tara deep links from OSHUN shell.

7.2 Tara Core Flows Inside OSHUN#

• Integrate meditation session launch flow.
• Integrate course progress/resume surfaces.
• Integrate favorites/bookmarks sync.
• Integrate audio playback handoff behavior.

7.3 Tara UX Polish#

• Re-skin Tara entry points to OSHUN design language.
• Preserve Tara-specific visual identity in contextual accents.
• Add fallback messaging for unavailable meditation assets.
• Add metrics for Tara launch and completion funnels.

Phase 8 - Domain Integration: Veritas#

8.1 Veritas Adapter and Contracts#

• Create libs/oshun/domain-veritas adapter package.
• Define Veritas feed item model for cross-domain surfaces.
• Implement veracity score card rendering contract.
• Implement Veritas deep links from OSHUN shell.

8.2 Veritas Core Flows Inside OSHUN#

• Integrate trending verification feed preview.
• Integrate claim detail drill-down entry point.
• Integrate follow-topic and alert preferences.
• Integrate saved claims and reading queue.

8.3 Veritas UX Polish#

• Design trust-signals and evidence snapshots for small screens.
• Ensure readability for high-density content.
• Add source attribution and confidence visuals.
• Add metrics for read depth and action conversion.

Phase 9 - Domain Integration: Nyx#

9.1 Nyx Integration Strategy#

• Decide initial mode: embed existing Nyx PWA vs native module rewrite.
• If embed-first: implement authenticated webview wrapper.
• If native-first: scaffold libs/oshun/domain-nyx module.
• Document migration steps from apps/nyx/mobile assets and logic.

9.2 Nyx Core Flows Inside OSHUN#

• Integrate nightly sky highlights on home dashboard.
• Integrate event reminders (meteor showers, eclipses, conjunctions).
• Integrate observation logs and saved sky objects.
• Integrate AR/sky map launch entry where device supports it.

9.3 Nyx UX Polish#

• Apply legibility-safe night mode treatment.
• Ensure brightness-sensitive interactions are ergonomic.
• Implement offline star map fallback for poor connectivity.
• Add metrics for session length and retained observers.

Phase 10 - Domain Integration: Arete#

10.1 Arete App Surfaces#

• Generate apps/arete/mobile (if needed for domain-owned experience).
• Generate apps/arete/web (if needed for domain-owned web).
• Build OSHUN-facing adapter libs/oshun/domain-arete.
• Map existing libs/arete/* capabilities to user-facing features.

10.2 Arete Core Flows Inside OSHUN#

• Integrate goals dashboard (short, mid, long horizon goals).
• Integrate habits tracker and streak components.
• Integrate journal capture and reflection prompts.
• Integrate AI coach summary cards and recommendations.
• Integrate wheel-of-life and balance check-ins.

10.3 Arete UX Polish#

• Implement calm, progress-oriented visual language.
• Implement low-friction daily check-in interaction.
• Implement optional accountability reminders.
• Add metrics for daily active reflection and streak stability.

Phase 11 - Cross-Domain Features (Core Value Layer)#

11.1 Universal Search#

• Implement search box in mobile and web shell.
• Add filters for Tara/Veritas/Nyx/Arete.
• Add blended result cards with domain badges.
• Add keyboard shortcuts for web/PWA search.

11.2 Unified Save/Bookmark#

• Define shared saved-item schema.
• Implement save/unsave actions per domain item type.
• Implement unified library screen.
• Implement sync conflict rules for saved states.

11.3 Cross-Domain Recommendations#

• Implement recommendation service contract in BFF.
• Add recommendation carousel on home.
• Add transparent explanation labels (why this is suggested).
• Add controls for user feedback (hide, less like this, more like this).

11.4 Notifications and Reminders#

• Implement push notifications registration in mobile.
• Implement web push for PWA.
• Implement notification center and settings.
• Add quiet hours and digest scheduling.

Phase 12 - Website and PWA (Associated With Mobile)#

12.1 OSHUN Website Foundation#

• Build public marketing pages in apps/oshun/web.
• Build authenticated dashboard mirroring core shell surfaces.
• Add domain landing sections for Tara/Veritas/Nyx/Arete.
• Add app download smart banners and deep links.

12.2 PWA Enablement#

• Add web app manifest with install metadata.
• Add service worker for core offline routes and assets.
• Add runtime caching for BFF and static media.
• Add background sync for queued user actions.
• Add install prompt UX and post-install guidance.

12.3 Responsive and Ergonomic Web UX#

• Ensure adaptive layouts from 320px to ultrawide.
• Tune touch-friendly interactions for tablet and mobile web.
• Ensure keyboard-first navigation support.
• Ensure accessible focus states and skip links.

12.4 Web/PWA Domain Surfaces#

• Add Tara web module entry points.
• Add Veritas web module entry points.
• Add Nyx PWA-native routes and install cues.
• Add Arete web check-in and dashboard routes.

Phase 13 - Offline, Sync, and Data Layer#

13.1 Data Strategy#

• Define cache policy matrix by endpoint/data type.
• Implement normalized local cache for shell-level data.
• Implement stale-while-revalidate flows where appropriate.
• Implement selective prefetch for likely next actions.

13.2 Offline Actions#

• Queue write actions while offline.
• Add retry/backoff and conflict resolution policies.
• Add user-visible sync states and retries.
• Add manual "sync now" control in settings.

13.3 Downloaded Content#

• Define offline download limits by domain and plan tier.
• Implement download manager UI and storage reporting.
• Implement eviction policy for old content.
• Implement corruption checks and repair actions.

Phase 14 - Accessibility, Internationalization, and Inclusion#

14.1 Accessibility Baseline#

• Enforce semantic labels and roles on all controls.
• Enforce minimum contrast for text and controls.
• Validate screen-reader flows on iOS and Android.
• Validate dynamic text scaling up to platform max settings.
• Validate motion-reduction behavior.

14.2 Internationalization#

• Extract all user-facing strings to i18n resources.
• Add locale negotiation for web/mobile.
• Add pluralization and date/time localization.
• Add RTL readiness checks.

14.3 Inclusion and Content Safety#

• Add content warning patterns where needed.
• Add safety escalation and reporting pathways.
• Add guidance copy for potentially sensitive topics.

Phase 15 - Observability, Analytics, and Experimentation#

15.1 Analytics Instrumentation#

• Define event dictionary in docs/releases/v1/reports/analytics-events.md.
• Implement shared analytics client wrappers.
• Instrument core funnels: onboarding, domain launch, retention.
• Add data quality checks for missing/invalid events.

15.2 Monitoring and Alerting#

• Add mobile crash monitoring with release metadata.
• Add web error monitoring with source maps.
• Add BFF latency/error dashboards.
• Add alert thresholds and on-call runbook.

15.3 Experimentation#

• Implement remote-config/feature-flag hooks.
• Add A/B framework for home layout and recommendation modules.
• Add guardrails for experiment blast radius.
• Add experiment analysis templates.

Phase 16 - Testing and Quality Gates#

16.1 Unit and Integration Testing#

• Add unit tests for all new libs/oshun/* packages.
• Add integration tests for domain adapters.
• Add contract tests between shell and BFF.
• Add snapshot tests for critical shell screens.

16.2 End-to-End Testing#

• Add mobile smoke tests for core navigation and auth.
• Add mobile domain-launch e2e tests (all four domains).
• Add web e2e tests for installable PWA and key funnels.
• Add deep-link and universal-link e2e coverage.

16.3 Non-Functional Testing#

• Add startup performance checks on real devices.
• Add scroll and animation jank regression tests.
• Add API resilience tests with partial domain outages.
• Add accessibility automated checks in CI.

16.4 Quality Gates#

• Require passing lint, typecheck, test, build for all changed projects.
• Require mobile and web smoke e2e before merge to main.
• Require bundle-size budget checks.
• Require lighthouse thresholds for PWA routes.

Phase 17 - Release Engineering and Distribution#

17.1 Mobile Release Pipeline#

• Configure EAS build profiles: development, preview, production.
• Configure signing credentials and secure secret handling.
• Configure TestFlight and Play tracks.
• Configure staged rollout percentages and rollback plan.

17.2 Web and PWA Release Pipeline#

• Configure production hosting for apps/oshun/web.
• Configure CDN caching headers for static assets.
• Configure service worker update strategy.
• Configure canary deploys and instant rollback.

17.3 Compliance and Store Readiness#

• Prepare privacy policy and terms pages linked in app and web.
• Prepare app store metadata and screenshots.
• Complete App Store and Play compliance checklists.
• Verify tracking/consent declarations are accurate.

Phase 18 - Launch, Beta, and Post-Launch Hardening#

18.1 Closed Beta#

• Recruit internal and external beta cohorts.
• Run beta scripts covering cross-domain daily journeys.
• Collect qualitative UX feedback and severity-tag issues.
• Fix high-severity bugs and ergonomic pain points.

18.2 Public Launch#

• Execute launch checklist runbook.
• Monitor real-time dashboards during launch window.
• Triage incidents with predefined severity protocol.
• Publish known-issues page for transparent communication.

18.3 First 30 Days#

• Review activation, D1/D7 retention, and feature adoption.
• Identify and ship top 10 UX friction fixes.
• Tune recommendation and notification quality.
• Rebalance roadmap based on real usage and support data.

Domain-Specific Acceptance Criteria#

Tara#

• User can launch meditation from OSHUN home in <= 2 taps.
• Resume session and favorites sync works across devices.
• Audio playback and interruption recovery are reliable.

Veritas#

• User can open top verification stories in <= 2 taps.
• Evidence and confidence indicators are readable on small screens.
• Save/follow flows persist across mobile and web.

Nyx#

• User can access nightly highlights and sky map quickly.
• Core content remains usable in low-connectivity mode.
• Night-mode ergonomics protect readability and comfort.

Arete#

• User can complete daily check-in in <= 60 seconds.
• Goals/habits/journal/coach surfaces are integrated in shell.
• Progress and streak visuals remain clear and motivational.

Cross-Platform Definition of Done#

• iOS app passes smoke, accessibility, and performance checks.
• Android app passes smoke, accessibility, and performance checks.
• Website passes responsive, accessibility, and SEO checks.
• PWA passes installability, offline, and update-flow checks.
• Shared auth and entitlements verified across all surfaces.
• Analytics events validated in production telemetry.
• Monitoring, alerts, and runbooks are live.
• Documentation is up to date in docs/releases/v1/*.

Suggested Initial Build Order (First 8 Weeks)#

Week 1#

• Finish Phase 0 decisions and audits.
• Scaffold apps/oshun/mobile, apps/oshun/web, libs/oshun/*.

Week 2#

• Ship shell navigation + design tokens + core UI primitives.
• Ship auth skeleton and BFF skeleton.

Week 3#

• Integrate Tara and Veritas initial domain launch adapters.
• Ship home dashboard v1 with real data.

Week 4#

• Integrate Nyx initial mode (embed or native baseline).
• Ship activity timeline and universal search v1.

Week 5#

• Integrate Arete v1 using existing libs/arete/*.
• Ship unified save/bookmark and notification center v1.

Week 6#

• Ship website + PWA installability + authenticated dashboard.
• Add offline queue and sync states.

Week 7#

• Hardening: tests, monitoring, analytics completeness, accessibility.
• Start beta rollout.

Week 8#

• Fix beta issues, finalize store/web release assets, launch.

Fast-Track Backlog (Optional)#

• Voice-first cross-domain assistant in shell home.
• Smart morning/evening routines spanning Tara + Arete.
• Cross-domain achievements and social accountability.
• Wearable companions for streaks, reminders, and summaries.
• Shared OSHUN desktop app surface if demand validates.