OSHUN Web App — Comprehensive Task Checklist (v2)

Created: 2026-02-21 Source: OSHUN_WEB_APP_ANALYSIS.md Scope: All gaps, UI overhaul, feature exposure, and architectural fixes

Legend#

• [ ] — Not started
• [~] — In progress
• [x] — Complete

1. Design System Foundation#

Before any feature work, establish a professional design system that all components will use.

1.1 Design Tokens & Theme#

• Create src/design-system/tokens.ts with typed color, spacing, typography, shadow, border-radius, z-index, and motion tokens
• Define domain accent palettes (Tara cyan, Arete emerald, Veritas sky, Nyx indigo) with full tint/shade scales (50-950)
• Define semantic color tokens (success, warning, error, info, neutral) with dark theme values
• Define typography scale (display, heading-1 through heading-4, body-lg, body, body-sm, caption, overline, label) with font-size, line-height, font-weight, and letter-spacing
• Define spacing scale (0, 1, 2, 3, 4, 5, 6, 8, 10, 12, 16, 20, 24, 32, 40, 48, 64) mapping to rem values
• Define shadow scale (sm, md, lg, xl, domain-glow) for depth and elevation
• Define motion tokens (duration: instant, fast, normal, slow; easing: standard, decelerate, accelerate, spring)
• Define z-index layers (base, sticky, dropdown, overlay, modal, toast, tooltip)
• Define border-radius scale (sm, md, lg, xl, full)
• Export a CSS-in-JS theme object and corresponding CSS custom properties
• Create src/design-system/globals-v2.css replacing the current monolithic globals.css with token-driven custom properties

1.2 Icon System#

• Select and integrate an icon library (Lucide React recommended: tree- shakable, MIT, consistent)
• Create src/design-system/icons.ts exporting domain-specific icon sets
• Define icons for: navigation (home, explore, activity, profile, search, notifications, settings), domains (tara lotus, arete summit, veritas shield, nyx star), actions (play, pause, close, add, remove, edit, save, share, bookmark, check, chevron, arrow, filter, sort), states (success, warning, error, info, loading, empty, locked), content types (audio, video, article, course, event, observation)

1.3 Core Component Library#

Create reusable, typed, accessible components in src/design-system/components/:

• <Button> — variants: primary, secondary, ghost, destructive; sizes: sm, md, lg; states: default, hover, active, focus, disabled, loading; with icon slot support (leading/trailing)
• <IconButton> — circular icon-only button with tooltip
• <Card> — variants: elevated, outlined, filled; with optional header, body, footer slots; supports domain accent border
• <Badge> — variants: default, success, warning, error, info, domain; sizes: sm, md
• <Tag> — removable tag/chip with optional icon; variants: default, outline, filled
• <ProgressBar> — determinate and indeterminate; with label, percentage text; animated fill; domain color support
• <ProgressRing> — circular progress indicator for stats and timers
• <StatTile> — value + label + optional trend indicator (up/down/flat) + optional icon
• <Avatar> — image or initials; sizes: xs, sm, md, lg, xl; with online status indicator
• <Skeleton> — loading placeholder for text, avatar, card, stat, list item; shimmer animation
• <EmptyState> — illustration + heading + description + optional CTA button
• <ErrorState> — error icon + message + retry button + optional detail toggle
• <Toast> — success, error, warning, info variants; auto-dismiss; action button; stack management
• <OverlaySheet> — bottom sheet / modal with backdrop; swipe-to-dismiss on mobile; header with close button; scrollable content area; sticky footer for actions
• <Tabs> — horizontal tab bar with domain accent underline; accessible role=tablist; animated indicator
• <SegmentedControl> — toggle between 2-4 options with sliding highlight
• <Dropdown> — accessible dropdown menu with keyboard navigation
• <SearchInput> — input with search icon, clear button, keyboard shortcut hint, loading state
• <ListItem> — standard list row with leading icon/avatar, title, subtitle, meta, trailing action; compact and default variants
• <SectionHeader> — overline label + heading + optional "View all" link
• <DomainPill> — colored pill showing domain name with accent dot
• <ConfidenceBadge> — Veritas-specific: color + label + percentage; with accessible text
• <VisibilityBadge> — Nyx-specific: excellent/good/fair with color and text
• <StreakIndicator> — flame icon + day count + optional calendar mini-view
• <HabitCheckbox> — proper checkbox with label, streak count, celebration animation on check
• <Tooltip> — accessible tooltip with arrow, delay, and placement options
• <Divider> — horizontal/vertical line with optional label
• <CalendarHeatmap> — GitHub-style contribution grid for habit/activity tracking
• <MiniChart> — sparkline chart for trend data in stat tiles
• <Confetti> — celebration animation component for achievements and milestones

1.4 Layout Components#

• <AppShell> — top-level layout with sidebar navigation, header bar, and main content area
• <Sidebar> — collapsible sidebar with logo, navigation links (with icons), domain quick-switch, user avatar, and settings link
• <TopBar> — header with breadcrumb, search trigger, notifications bell (with unread count badge), and user menu
• <PageContainer> — max-width container with responsive padding
• <Grid> — responsive grid utility (1-4 columns) with breakpoint control (implemented as CSS utility classes in globals-v2.css)
• <Stack> — vertical/horizontal flex layout with gap control (implemented as CSS utility classes in globals-v2.css)
• <DomainSurfaceLayout> — domain-specific layout with accent-colored header, breadcrumb back to shell, and domain-specific nav tabs

2. Navigation & Shell Redesign#

2.1 Primary Navigation#

• Replace the current pill-button nav (ShellRouteNavigator) with a proper sidebar navigation pattern
• Add OSHUN logo/wordmark to the top of the sidebar
• Add icons to each navigation item (Home, Explore, Activity, Profile)
• Add domain quick-launch section in sidebar with domain icons and accent colors
• Add active state indicator (accent-colored left border or background highlight)
• Add collapsed/expanded state for sidebar (icon-only vs. icon + label)
• Add user avatar + name at the bottom of sidebar with dropdown menu ( settings, subscription, logout)
• Implement mobile responsive: convert sidebar to bottom tab bar on screens < 768px
• Add keyboard shortcuts indicator next to navigation items (Alt+1, Alt+2, etc.)
• Add notification badge on Activity nav item showing unread count

2.2 Domain Navigation#

• Add breadcrumb trail when inside a domain surface (Shell > Domain > Sub- route)
• Add domain-specific tab navigation within each surface (e.g., Tara: Sessions | Courses | Breathwork | Stats)
• Add "back to shell" button/gesture from domain surfaces
• Persist domain navigation state across domain switches (return to where you left off)
• Add domain transition animation (smooth morph from card to full surface)

2.3 Global Features#

• Redesign Universal Search with command palette style (Cmd/Ctrl+K) — search across all domains, recent searches, quick actions
• Add global notification dropdown in top bar (not inline on home page)
• Add global keyboard shortcut help modal (Shift+?)
• Add "What's new" changelog dropdown for feature updates
• Add breadcrumb component showing navigation hierarchy

3. Home Dashboard Redesign#

3.1 Hero Section#

• Replace static text greeting with dynamic, time-aware greeting using user name (from profile store)
• Add a "Continue where you left off" card showing the last domain interaction with resume CTA
• Add weather/sky conditions mini-widget for Nyx integration
• Add daily motivation/affirmation from Arete
• Remove the static "Your OSHUN dashboard for Tara, Veritas, Nyx, and Arete" title — replace with contextual summary

3.2 KPI Grid#

• Replace hardcoded metrics with real data from BFF
• Add trend indicators (up/down arrow with percentage change)
• Add sparkline mini-charts in each KPI tile
• Make KPI tiles interactive (click to navigate to relevant section)
• Add animation on data load (count-up effect for numbers)

3.3 Daily Plan#

• Replace hardcoded "Tara breathwork, Veritas deep read, and Nyx evening check-in are queued" with real queued actions from all domains
• Add ability to check off completed daily plan items
• Add ability to customize daily plan (add/remove/reorder)
• Show actual completion progress (not static "1 of 3")
• Add time estimates for each plan item

3.4 Activity Feed#

• Replace hardcoded activity list with real-time data from BFF activity endpoint
• Add domain color indicator on each activity item
• Add relative timestamps that auto-update
• Add "View all" link to Activity page
• Limit to 5 most recent items with smooth load

3.5 Domain Cards#

• Redesign domain cards with larger visual presence (illustration or gradient background)
• Add real-time stats to each domain card (not hardcoded)
• Add "last active" timestamp to each domain card
• Add quick action buttons directly on domain cards (not just a single CTA)
• Add notification count badge on domains with unread items
• Add progress ring showing domain engagement score
• Add hover state with preview of recent activity in that domain

4. Tara Domain — Full Feature Exposure#

4.1 Session Library#

• Build full session browse page with grid/list toggle
• Add category filter sidebar (Breathwork, Focus, Sleep, Loving-kindness, Movement, Reflection)
• Add level filter (Beginner, Intermediate, Advanced, All levels)
• Add duration filter (5 min, 10 min, 15 min, 20 min, 25+ min)
• Add search within sessions
• Add sort controls (popularity, duration, newest, recommended)
• Display instructor info on each session card
• Add "Start" button on each session card that opens the session player
• Add "Favorite" toggle on each session card with persist to BFF
• Add session detail overlay with full description, instructor bio, related sessions, and user reviews

4.2 Session Player — Complete Overhaul#

• Replace inline-styled SessionPlayer with design system components
• Add animated timer visualization (circular progress ring with phase indicator)
• Add phase timeline showing upcoming phases (inhale, hold, exhale, hold)
• Add audio playback integration (background music / guided voice)
• Add volume control
• Add skip forward/backward controls
• Add session complete screen with stats (duration, heart rate zone if available, focus score)
• Add post-session reflection prompt (optional journal entry)
• Add "Share session" functionality
• Add "Add to favorites" from within player

4.3 Breathwork Timer — Complete Overhaul#

• Replace inline-styled BreathworkTimer with design system components
• Add breathing pattern selection: Box Breathing (4-4-4-4), Relaxing Breath (4-7-8), Energizing Breath (Wim Hof), Custom
• Add visual breathing guide (expanding/contracting circle with smooth CSS animation, not transform scale)
• Add haptic feedback option (for mobile)
• Add ambient soundscape selection (ocean, rain, silence, forest, singing bowl)
• Add cycle count customization (1, 3, 5, 10, custom)
• Add session summary on completion with celebration animation
• Add streak integration (count toward daily meditation streak)

4.4 Courses#

• Build course detail page with lesson list
• Add lesson progress tracking (completed, current, locked)
• Add lesson player (reuse session player)
• Add course progress overview (progress ring, lessons completed, estimated time remaining)
• Add "Continue course" CTA on course card
• Add course completion certificate/badge
• Build course browse page with category/level filters

4.5 Favorites#

• Build favorites page showing all saved sessions and courses
• Add remove from favorites functionality
• Add sort by recently saved / most played
• Add empty state for when no favorites exist

4.6 Statistics & History#

• Build Tara stats page with meditation history calendar heatmap
• Add weekly/monthly/all-time toggle
• Add total time meditated chart (line graph)
• Add session frequency chart (bar graph)
• Add streak calendar view with longest streak, current streak, streak freezes
• Add insights section (best time of day, most consistent habit, favorite category)
• Add session history list with date, duration, type, and rating

4.7 Integration with @tara/ Libraries#

• Connect @tara/analytics for real usage tracking
• Connect @tara/content for dynamic session/course loading
• Use @tara/features for feature flag-gated content
• Connect @tara/ui theme tokens to design system

5. Arete Domain — Full Feature Exposure#

5.1 AI Coach#

• Build AI Coach chat interface within Arete surface
• Integrate @arete/ai-coach library for conversational coaching
• Support CBT-based coaching sessions
• Add personalized recommendations based on user patterns
• Add pattern recognition visualizations (habit patterns, mood cycles, energy levels, productivity peaks)
• Add smart notification integration (coach suggests timely actions)
• Add journal analytics NLP (sentiment, emotion, topic extraction) with visual summary
• Add coach history/conversation log

5.2 Habits — Full @arete/habits Integration#

• Build habit creation form (name, category, frequency, cue, routine, reward)
• Implement Atomic Habits cue-routine-reward loop UI
• Implement Four Laws of Behavior Change framework UI (make it obvious, attractive, easy, satisfying)
• Build habit stacking interface (chain habits together)
• Add celebration/reinforcement animations on habit completion
• Implement streak system with forgiveness (configurable grace days)
• Add identity-based habits UI ("I am a person who...")
• Add keystone habit identification and prominence
• Build habit analytics dashboard (completion rates, time-of-day patterns, trend charts)
• Add habit reminders/notifications configuration
• Add habit calendar heatmap view
• Add habit detail page with history, streaks, analytics
• Add habit archival (soft delete) for completed/abandoned habits
• Add habit editing (modify frequency, cue, routine, reward)

5.3 Goals — Full @arete/goals Integration#

• Build goal creation form (title, description, target date, milestones, category, linked habits)
• Add goal-habit alignment visualization (which habits support which goals)
• Add milestone tracking within goals (sub-goals with progress)
• Add goal categories (Health, Career, Relationships, Learning, Financial, Creative, Custom)
• Add goal timeline/roadmap view
• Add goal progress chart (line graph over time)
• Add goal sharing/accountability partner feature
• Add goal archival for completed/abandoned goals
• Add goal priority ranking (drag-to-reorder)
• Add SMART goal validation helper (Specific, Measurable, Achievable, Relevant, Time-bound)

5.4 Gamification — @arete/gamification Integration#

• Build achievements/badges gallery page
• Add points system with visible point balance
• Add level/rank system with progress to next level
• Add leaderboard (opt-in, anonymized)
• Build challenge system (daily challenges, weekly challenges, custom)
• Add reward redemption UI (if reward mechanics are defined)
• Add achievement unlock celebration animation (confetti + toast)
• Add challenge creation and sharing

5.5 Journal — Full @arete/journal Integration#

• Build full journal editor (rich text: bold, italic, lists, headers)
• Add mood selector (emoji or rating scale)
• Add reflection prompt library (rotating daily prompts)
• Add journal entry detail view with date, mood, word count, reading time
• Add journal search (full-text)
• Add journal calendar view (entries by date)
• Add journal analytics dashboard (mood trends, writing frequency, topic clouds, sentiment over time)
• Add journal export (PDF, plain text)
• Add privacy controls (lock individual entries)
• Add gratitude journal mode (daily 3 gratitudes)
• Add journal templates (morning pages, evening reflection, weekly review, gratitude)

5.6 Balance — @arete/balance Integration#

• Build work-life balance assessment questionnaire
• Add energy management tracker (track energy levels throughout the day)
• Add recovery tracking (sleep quality, rest day logging)
• Add balance score visualization (radar chart: work, health, relationships, growth, recreation)
• Add balance recommendations based on assessment results

5.7 Affirmations — @arete/affirmations Integration#

• Build daily affirmation display (full-screen card with motivational typography)
• Add affirmation creation (write custom affirmations)
• Add affirmation categories (confidence, health, success, relationships, gratitude)
• Add affirmation scheduling (morning, evening, custom times)
• Add affirmation tracking (which affirmations resonate most)
• Add affirmation sharing

5.8 Time Management — @arete/time Integration#

• Build Pomodoro timer with customizable work/break durations
• Add time blocking calendar view
• Add calendar analysis (where is time being spent)
• Add focus mode (block distractions during Pomodoro sessions)
• Add time tracking reports (daily, weekly, monthly)

5.9 Vision — @arete/vision Integration#

• Build vision statement creator (guided wizard)
• Add vision board with images, text, and goals
• Add long-term goal planning timeline (1 year, 5 year, lifetime)
• Add vision-to-goal alignment mapping

5.10 7 Habits Framework — @arete/seven-habits Integration#

• Build 7 Habits dashboard (Be Proactive, Begin with End in Mind, Put First Things First, Think Win-Win, Seek First to Understand, Synergize, Sharpen the Saw)
• Add habit tracking per Covey principle
• Add weekly planning tool (Big Rocks approach)
• Add Eisenhower matrix for prioritization
• Add Circle of Influence vs. Circle of Concern visualization

6. Veritas Domain — Full Feature Exposure#

6.1 Article Experience#

• Build full article reader with proper typography (serif font for body text, adequate line-height and max-width)
• Add reading progress indicator (progress bar at top of article)
• Add estimated reading time
• Add article highlight and annotation system
• Add article sharing (social, copy link, email)
• Add article versioning timeline (show edits/updates over time from @veritas/article-versioning)
• Add related articles sidebar/footer
• Add article text-to-speech

6.2 Claim Verification & Fact-Checking#

• Build claim detail page with full evidence chain
• Show confidence score breakdown (methodology, evidence quality, source reliability)
• Add interactive verification trail (timeline of evidence discovery)
• Add user claim submission form (submit a claim for fact-checking)
• Integrate @veritas/fact-checking workflow UI
• Add claim status tracking (submitted, investigating, verified, debunked, inconclusive)
• Add "See both sides" view showing arguments for and against a claim

6.3 Bias Detection — @veritas/bias-detection Integration#

• Add bias indicator badge on articles (political lean, linguistic bias score)
• Build bias analysis detail view (what specific language triggers bias detection, comparison with neutral phrasing)
• Add coverage bias overview (which topics are over/under-covered)
• Add source comparison view (how different sources cover the same story)

6.4 Knowledge Graph — @veritas/knowledge-graph Integration#

• Build entity relationship visualization (force-directed graph)
• Add entity profiles (people, organizations, topics) with connection maps
• Add story timeline showing how events connect
• Add entity search and filtering

6.5 Story Clustering — @veritas/story-clustering Integration#

• Build story cluster view (group related articles from different sources)
• Add timeline view showing story evolution
• Add source comparison within a cluster
• Add "key developments" summary for each cluster

6.6 Source Directory — Complete Overhaul#

• Build comprehensive source directory with search and filters
• Add source profile pages (credibility score, publication history, bias rating, coverage areas)
• Add author profiles with verification status and credentials
• Add source comparison tool
• Add "Follow source" functionality
• Add source credibility score breakdown

6.7 Reading Queue — Complete Overhaul#

• Build reading queue page with sort (date saved, read time, source)
• Add reading queue categories/folders
• Add reading queue search
• Add reading queue offline support (pre-download articles)
• Add estimated total reading time for entire queue
• Add "Mark as read" without opening
• Add annotation/notes on queued items
• Persist queue to BFF (not local state only)

6.8 Topic Management#

• Build topic browser with hierarchical categories
• Add topic detail page with latest articles, key claims, related topics
• Add topic alert configuration (frequency, importance threshold)
• Add topic following/unfollowing
• Add topic analytics (coverage trends, sentiment over time)

6.9 Newsletter — @veritas/newsletter Integration#

• Build newsletter subscription configuration (topics, frequency, format)
• Add newsletter preview before sending
• Add newsletter archive view

6.10 Agents — @veritas/agents Integration#

• Build agent pipeline status dashboard (show which agents are processing what)
• Add configurable agent preferences (research depth, source diversity)
• Surface journalism agent outputs (research summaries, source discoveries)
• Surface fact-check agent progress on submitted claims

6.11 RAG — @veritas/rag Integration#

• Add "Ask a question" feature powered by RAG (ask questions about a topic, get answers with source citations)
• Add research assistant chat interface for deep-dive investigations
• Add evidence compilation from multiple sources for a given claim

7. Nyx Domain — Full Feature Exposure#

7.1 Interactive Sky Map#

• Build canvas/WebGL-based interactive star chart (or integrate a JS star map library)
• Add zoom and pan controls
• Add constellation overlay toggle (with multi-cultural options from @nyx/catalogs)
• Add planet positions with labels
• Add deep sky object markers (nebulae, galaxies, clusters)
• Add satellite track overlay (ISS path)
• Add compass/orientation mode (use device orientation on mobile)
• Add time slider to see sky at different times tonight
• Add click-on-object detail popup (name, magnitude, coordinates, best viewing tips)

7.2 Solar Activity — @nyx/realtime-solar Integration#

• Build solar activity dashboard with current solar wind speed, density, and magnetic field
• Add aurora forecast map (Kp index, viewing probability by latitude)
• Add CME (Coronal Mass Ejection) alert system
• Add solar flare history and predictions
• Add sunspot number tracking
• Add aurora notification configuration

7.3 Near-Earth Objects — @nyx/realtime-neo Integration#

• Build NEO tracking dashboard showing upcoming close approaches
• Add impact risk assessment visualization (Torino scale)
• Add NEO orbit visualization
• Add NEO detail pages (size, velocity, distance, next approach)
• Add NEO alert configuration

7.4 Time Travel — @nyx/time-travel Integration#

• Build "What did the sky look like on..." date picker
• Add historical event sky recreation (e.g., "Sky on the night of the moon landing")
• Add future event preview (sky on upcoming birthday, solstice, etc.)
• Add ecliptic visualization for past/future eclipses

7.5 Education — @nyx/education Integration#

• Build astronomy learning module browser
• Add beginner's guide to stargazing (interactive tutorial)
• Add constellation identification quiz
• Add glossary of astronomical terms
• Add "Object of the week" educational feature
• Add difficulty-graded observation challenges

7.6 Catalog Access — @nyx/catalogs Integration#

• Build catalog browser (Messier, NGC, IC, Caldwell, Herschel, etc.)
• Add catalog object detail pages (image, description, location, best viewing conditions)
• Add observation checklist (mark objects as observed with notes/photos)
• Add catalog filtering (type, magnitude, constellation, season)
• Add "What can I see tonight?" filtered by equipment and conditions

7.7 Observation Log — Complete Overhaul#

• Build observation entry form (target, date/time, conditions, equipment, notes, rating)
• Add photo upload for observations
• Add observation sharing
• Add observation statistics (total objects observed, total sessions, hours logged)
• Add observation calendar view
• Add equipment profile setup (telescopes, eyepieces, filters, binoculars)
• Add observation session planner (plan tonight's observation run)

7.8 Sonification — @nyx/audio Integration#

• Build sonification player (listen to astronomical data converted to sound)
• Add different sonification modes (star brightness, pulsar rhythms, solar wind)
• Add interactive sonification (hover over star chart to hear)

7.9 Sky Conditions — Complete Overhaul#

• Integrate geolocation for accurate sunset/sunrise/twilight times
• Add weather forecast integration (cloud cover, humidity, wind)
• Add light pollution map (interactive, based on user location)
• Add moon phase calendar with visual lunar phase diagrams
• Add "Best viewing tonight" recommendation card
• Add viewing conditions trend (next 7 days forecast)

8. Explore Page — Redesign#

• Add trending content carousel (top items from each domain)
• Add personalized recommendations section (based on usage patterns)
• Add "New in each domain" section highlighting recently added content
• Add community picks / most popular this week
• Add cross-domain content timeline (all content chronologically)
• Redesign collection cards with richer visuals (gradient backgrounds, domain icons)
• Add collection detail pages (navigate into a collection to see all items)
• Add editorial spotlight articles with featured images
• Add search results page with domain-grouped results, relevance scoring, and filters
• Add "Discover" mode — random interesting content from any domain
• Add recently viewed history

9. Activity Page — Redesign#

• Replace hardcoded timeline data with real BFF data
• Add domain filter tabs on timeline (All, Tara, Veritas, Nyx, Arete)
• Add kind filter (Updates, Reminders, Events, Insights)
• Add bulk mark-as-read functionality
• Add swipe-to-dismiss on mobile for notification items
• Add action buttons on timeline items (e.g., "Resume session", "Read article", "Open observation")
• Redesign achievement cards with visual badge icons and unlock animations
• Add achievement detail overlay (requirements, progress, tips)
• Add milestone celebration when achieved (confetti + overlay)
• Add weekly/monthly activity digest summary (auto-generated recap)
• Add activity export (share weekly summary)
• Add streak calendar visualization (grid showing all active streaks across domains)

10. Profile Page — Redesign#

• Build comprehensive profile page with account info, preferences, and settings
• Add profile photo upload/change
• Add display name editing
• Add email/notification preferences with per-domain granularity
• Add privacy settings (data sharing, analytics opt-in)
• Add subscription/tier management display
• Add connected services/integrations list
• Add data export/download option
• Add theme preference (dark/light/system — even if only dark is available now, add the toggle)
• Add accessibility preferences (reduced motion, high contrast, font size)
• Add per-domain statistics summary (total usage for each domain)
• Add account deletion request flow
• Add timezone/locale settings
• Add push notification management

11. Data Architecture & API Layer#

11.1 API Client#

• Create centralized API client (src/lib/api-client.ts) using a proper HTTP client with:
  • Environment-aware base URL (not hardcoded localhost:4010)
  • Token management (read from auth context, handle refresh)
  • Request/response interceptors
  • Error handling with typed error responses
  • Request deduplication
  • Retry logic with exponential backoff

11.2 Data Fetching#

• Integrate SWR or React Query (TanStack Query) for data fetching with:
  • Automatic caching and revalidation
  • Optimistic updates
  • Background refetch
  • Loading/error state management
  • Infinite scroll support
  • SSR hydration support
• Create typed hooks for each BFF endpoint:
  • useHome() — home feed data
  • useRecommendations(domain) — domain recommendations
  • useActivity(cursor?) — activity timeline with pagination
  • useNotifications() — notification feed
  • useSearch(query) — global search
  • useProfile() — user profile
  • useEntitlements() — subscription tier
  • useDomainData(domain) — domain-specific aggregate data

11.3 State Management#

• Implement a proper auth context/provider (replace hardcoded Bearer token)
• Create domain state stores (Zustand or context-based) for:
  • Tara: current session, favorites, course progress
  • Arete: habits, goals, journal entries, check-in state
  • Veritas: reading queue, followed topics, saved claims
  • Nyx: observation log, equipment profile, sky preferences
• Add state persistence (localStorage/IndexedDB) for offline support
• Add state hydration from BFF on app load

11.4 Real-time Integration#

• Integrate @oshun/websocket for live updates
• Add real-time notification delivery (no polling)
• Add live activity feed updates
• Add domain-specific real-time features (Nyx ISS flyover alerts, Veritas breaking news)

12. Psyche AI Platform Integration#

12.1 AI Assistant#

• Build global AI assistant panel (slide-out from right side)
• Integrate @psyche/dialogue-manager for multi-turn conversations
• Add domain-aware context (assistant knows which domain you're in)
• Add tool integration (assistant can create habits, save articles, start sessions)
• Add voice input option (using @psyche/speech-recognition)
• Add TTS response option (using @psyche/tavus-tts)

12.2 Smart Features#

• Add engagement detection (using @psyche/engagement-detector) to suggest breaks or domain switches
• Add knowledge context integration (using @psyche/knowledge-context) for contextual help
• Add content relevance scoring for personalized feeds

13. Responsive Design & Mobile#

• Add responsive breakpoints to all grid layouts (KPI grid, split grid, domain grid, collection grid, achievement grid)
• Add mobile bottom tab bar navigation (appears below 768px)
• Add mobile-optimized overlay sheets (full-screen on small screens, bottom sheet on medium)
• Add touch gesture support (swipe to go back, swipe to dismiss overlay, pull to refresh)
• Add safe-area-inset support for notched devices
• Test and fix all pages at widths: 320px, 375px, 414px, 768px, 1024px, 1440px, 1920px
• Add responsive typography (larger base on desktop, smaller on mobile)
• Add responsive spacing (tighter on mobile)
• Add responsive images (if/when images are added to domain surfaces)
• Add mobile-specific quick action patterns (floating action button or bottom sheet)

14. Accessibility#

• Add visible focus indicators on all interactive elements (:focus-visible outline with accent color)
• Add @media (prefers-reduced-motion: reduce) rules to ALL animations (including inline-styled ones in overlays)
• Replace the habit toggle <article onClick> with proper <input type="checkbox"> with role and aria-checked
• Add aria-live="polite" regions for dynamic content updates (fetch results, timer changes, toast notifications)
• Add skip-to-content link that's visible on focus
• Add proper heading hierarchy on every page (h1 > h2 > h3, no skips)
• Ensure all color-coded information has a text/icon alternative (confidence badges, visibility badges, habit completion)
• Add proper alt text for all future images/illustrations
• Test with screen reader (VoiceOver on macOS)
• Test keyboard-only navigation through all flows
• Add ARIA labels to all icon-only buttons
• Ensure minimum touch target size of 44x44px on all interactive elements
• Add prefers-color-scheme support (even if only dark for now, ensure light mode doesn't break)

15. Performance#

• Add loading skeletons on all pages (show placeholder layout while data fetches)
• Implement code splitting per domain surface (lazy load TaraSurface, AreteSurface, etc.)
• Add image optimization pipeline (when images are added)
• Add resource prefetching for likely next navigation targets
• Optimize CSS by removing unused styles from globals.css (tree-shake with PostCSS or migrate to CSS modules per component)
• Add Core Web Vitals monitoring (LCP, FID, CLS)
• Add bundle size monitoring
• Ensure Lighthouse performance score >= 90
• Add proper caching headers for static assets
• Implement virtualized lists for long content (session library, article feeds, observation logs)

16. Testing#

• Add unit tests for all design system components
• Add integration tests for each domain surface (render with mock data, verify interactions)
• Add e2e tests for critical user flows:
  • Home > Tara > Start session > Complete > See stats
  • Home > Arete > Check in > Toggle habit > Create journal entry
  • Home > Veritas > Read article > Save to queue > View queue
  • Home > Nyx > View tonight's sky > Log observation
• Add visual regression tests for design system components
• Add accessibility tests (axe-core integration)
• Add responsive design tests (render at multiple breakpoints)
• Ensure test coverage >= 80% for all new components
• Add BFF integration tests for data fetching hooks

17. Documentation & Developer Experience#

• Add Storybook for design system component documentation
• Document component API (props, variants, examples) in Storybook stories
• Add design system usage guidelines (when to use which component)
• Add domain feature inventory (which library features map to which UI components)
• Document BFF API contract for frontend developers
• Add architecture decision records (ADRs) for major choices (state management, data fetching, design system approach)

18. Error Handling & Edge Cases#

• Add global error boundary with user-friendly error page
• Add per-domain error boundaries that allow other domains to continue working
• Add offline detection banner (using navigator.onLine + BFF health check)
• Add empty state handling for every list/grid (sessions, articles, observations, habits, goals, journal entries)
• Add loading state handling for every async operation
• Add error retry patterns for failed BFF requests
• Add toast notifications for transient errors
• Add graceful degradation when specific domain services are down
• Add form validation with clear error messages on all input forms (goal creation, journal entry, observation log, claim submission)

19. Onboarding & First-Time Experience#

• Build onboarding wizard for new users (domain selection, interests, notification preferences)
• Add domain-specific first-time experience (guided tour of key features)
• Add progressive disclosure — show features gradually as user explores
• Add contextual help tooltips on first visit to each section
• Add empty-to-full state transitions (show helpful guidance when lists are empty, celebrate first entry)
• Add "Quick start" templates for each domain (pre-populated habits for Arete, suggested topics for Veritas, beginner observation list for Nyx, starter course for Tara)

20. Cross-Domain Integration#

• Build "Cross-domain rituals" feature — sequences that span multiple domains (e.g., "Morning routine": Tara meditation > Arete check-in > Veritas morning brief)
• Add cross-domain search results on global search
• Add cross-domain activity correlation (e.g., "Days you meditate, you read more articles")
• Add cross-domain recommendations (e.g., "Based on your Nyx interest in Mars, here's a Veritas article about Mars exploration")
• Add unified streak tracking across domains
• Add cross-domain achievement badges (already exist in activity page, but need real tracking)

21. Production Readiness — Security & Infrastructure#

21.1 Security Headers (CRITICAL — Before Launch)#

• Add Content-Security-Policy (CSP) header in next.config.mjs with script-src, style-src, img-src, connect-src, font-src, frame-ancestors directives
• Add Strict-Transport-Security (HSTS) header with max-age=31536000, includeSubDomains, preload
• Add X-Permitted-Cross-Domain-Policies: none
• Add Cross-Origin-Opener-Policy: same-origin
• Add Cross-Origin-Resource-Policy: same-origin
• Review and tighten Permissions-Policy (currently allows some APIs)
• Add Subresource Integrity (SRI) for any third-party scripts
• Configure CORS properly in BFF for production domains

21.2 Missing Critical Files (CRITICAL — Before Launch)#

• Create src/app/error.tsx — global error boundary page with user-friendly error UI, retry button, and error reporting
• Create src/app/not-found.tsx — custom 404 page with search, navigation to home, and domain links
• Create src/app/loading.tsx — global loading skeleton matching shell layout
• Create public/robots.txt with allow/disallow rules for search engines
• Create public/sitemap.xml generator (use next-sitemap or custom) for all public routes
• Add public/favicon.ico and public/favicon.svg with OSHUN branding
• Create public/.well-known/assetlinks.json for Android app association
• Create public/.well-known/apple-app-site-association for iOS deep linking
• Add PWA manifest screenshots (currently empty array) for app store-like install experience

21.3 Next.js Middleware#

• Create src/middleware.ts with:
  • Authentication check — redirect unauthenticated users to /welcome
  • Session validation — verify token freshness
  • Rate limiting for sensitive routes
  • Request ID injection for tracing
  • Locale detection (for future i18n)
  • Legacy route redirects

21.4 Legal & Compliance#

• Create cookie consent banner component (GDPR compliance)
• Create cookie policy page
• Create accessibility statement page (WCAG 2.1 AA commitment)
• Add privacy policy link to footer/profile
• Add terms of service link to footer/profile
• Add CCPA compliance page (for California users)
• Add data processing agreement page (for EU users)

21.5 SEO#

• Add canonical URL meta tag to layout
• Add structured data (JSON-LD) for organization and application
• Add Open Graph images for social sharing (currently text-only OG)
• Add Twitter card images
• Ensure all pages have unique title and description meta tags
• Add meta tags for mobile app deep linking (already partial)

22. BFF Endpoint Integration — Achievements & Social#

22.1 Achievement System (17 BFF endpoints ready)#

• Build achievement gallery page showing all definitions organized by category and domain
• Build achievement detail view with requirements, progress, tips, and unlock status
• Add achievement unlock celebration overlay (confetti + detail card)
• Add "newly unlocked" badge/notification that links to achievement detail
• Integrate POST /v1/achievements/evaluate on meaningful user actions
• Add achievement progress tracking in domain surfaces (show relevant achievement progress)
• Add achievement summary widget on home dashboard
• Add achievement tier filtering (bronze, silver, gold, platinum)
• Add domain-specific achievement views within each domain surface

22.2 Social Accountability Partnerships (8 BFF endpoints ready)#

• Build accountability partner invite flow (search by username/email, send invite)
• Build partner invite management (accept, decline, view pending)
• Build partner dashboard showing both users' progress side-by-side
• Add partner check-in form (mood, highlights, challenges)
• Add encouragement messaging between partners
• Build partnership health visualization (engagement score, consistency)
• Add partnership insights page with trend analysis
• Add partnership ending flow with confirmation

22.3 Challenges System (7 BFF endpoints ready)#

• Build challenge browse page (filter by domain, difficulty, duration)
• Build challenge detail page with rules, participants, leaderboard
• Add challenge join flow with commitment confirmation
• Build daily challenge progress recording UI
• Build challenge leaderboard with rank, streak, completion rate
• Add challenge completion celebration
• Add user's active/completed challenges list

23. BFF Endpoint Integration — Routine Automation#

23.1 Routine System (18 BFF endpoints ready)#

• Build routine template browser (morning/evening categories with domain indicators)
• Build custom routine creator (select steps from any domain, set schedule)
• Build routine detail page (steps list, schedule, notifications toggle)
• Build routine execution UI (step-by-step guided flow with progress bar)
  • Step display with domain accent color
  • Advance to next step button
  • Pause/resume controls
  • Abandon with confirmation
  • Auto-advance timer for timed steps
• Build active execution status bar (persistent banner showing current routine progress)
• Build routine history page with completion rates and streaks
• Build routine summary dashboard with statistics
• Add routine scheduling UI (frequency: daily, weekdays, weekends, custom day selection)
• Add routine notification preferences (reminder time, snooze)
• Replace hardcoded "Daily Plan" on home page with real routine data
• Add routine recommendations based on time of day and user patterns
• Add routine editing (reorder steps, add/remove steps, rename)
• Add routine duplication (clone a routine to customize)

24. BFF Endpoint Integration — Assistant & Audio#

24.1 Voice/Text Assistant (4 BFF endpoints ready)#

• Build assistant slide-out panel accessible from any page (bottom-right FAB or sidebar button)
• Implement text input chat interface with message history
• Add voice input mode with microphone button and speech recognition
• Display assistant responses with domain-aware context indicators
• Integrate domain-specific actions from assistant (e.g., "Start a Tara session" → opens session player)
• Add session management (create new, continue previous, list history)
• Add assistant suggestions based on current page context
• Add typing indicator and loading states

24.2 Session Audio Integration (BFF endpoint ready)#

• Integrate GET /v1/sessions/:sessionId/audio into SessionPlayer component
• Add HTML5 <audio> element with proper controls
• Add audio quality selection (standard, high, lossless)
• Add audio buffering/loading states
• Add audio error handling (failed to load, network interruption)
• Add background audio continuation (audio plays when overlay is closed)
• Add audio volume control
• Add playback speed control (0.5x, 1x, 1.5x, 2x)

24.3 Recommendation Feedback (BFF endpoint ready)#

• Add "More like this" / "Less like this" / "Hide" buttons on all recommendation cards across all domains
• Integrate POST /v1/recommendations/feedback on user interactions
• Add optional reason field on "hide" action
• Add visual feedback on recommendation dismissal (slide out animation)

25. BFF Endpoint Integration — Favorites & Streaks#

25.1 Favorites System (3 BFF endpoints ready)#

• Build favorites page for Tara (grid of saved sessions with remove option)
• Add favorite toggle button to all session cards and session player
• Integrate POST /v1/favorites/:meditationId for adding
• Integrate DELETE /v1/favorites/:meditationId for removing
• Add optimistic UI updates on favorite toggle
• Extend favorites concept to other domains (Veritas saved articles, Nyx saved objects) when BFF endpoints expand

25.2 Wearable-Inspired Web Features#

• Adapt wearable streak comparison (GET /v1/wearable/streaks/comparison) for web dashboard — show all domain streaks side-by-side
• Adapt wearable glance summary (GET /v1/wearable/glance) as a compact dashboard widget
• Adapt daily/weekly summary generation for web email digest or in-app summary page
• Adapt smart reminders system for web push notifications
• Build complication-inspired mini-widgets for home dashboard (domain- specific compact stat cards)

25.3 Desktop-Inspired Web Features#

• Adapt focus mode toggle for web (dim non-essential UI, hide notifications)
• Adapt keyboard shortcuts system (already partially exists in AccessibilityShell)
• Adapt widget sidebar concept as a collapsible side panel with customizable widgets
• Build deep link builder for sharing domain-specific content URLs

26. Overlay Components — Complete Rewrite#

All 10 overlay components need a ground-up rewrite. These are tracked individually because the current implementations have critical issues.

26.1 Shared Overlay Infrastructure#

• Create <OverlaySheet> base component (used by all overlays) with:
  • Focus trap on open, focus restore on close
  • Escape key to close
  • Backdrop click to close
  • Swipe-to-dismiss on mobile
  • Proper aria-modal="true", role="dialog", aria-labelledby
  • Smooth enter/exit animations
  • Scrollable body with sticky header/footer
  • Responsive sizing (full-screen on mobile, centered sheet on desktop)

26.2 Tara Overlays#

• Rewrite BreathworkTimer — remove all inline styles, use design system components, add pattern selection, add ambient sounds, respect prefers-reduced-motion
• Rewrite SessionPlayer — add real audio integration, add functional seek/skip controls, add progress persistence, add post-session reflection

26.3 Arete Overlays#

• Rewrite DailyCheckInOverlay — fix missing save logic, add proper form validation, add mood emoji accessibility (replace with labeled options), add draft auto-save
• Rewrite JournalOverlay — add rich text editing, add mood selector, add tags, add entry persistence to BFF, add auto-save indicator
• Rewrite GoalsOverlay — fix setNewGoalTile typo, fix Date.now() ID generation, add proper goal CRUD with BFF integration, add milestones, add categories

26.4 Veritas Overlays#

• Rewrite ArticleReaderOverlay — add dynamic article loading (not hardcoded content), add functional Save/Share buttons, add reading progress indicator, add text size controls, add TTS
• Rewrite ReadingQueueOverlay — pass article data to reader (currently passes nothing), add persistence to BFF, add drag-to-reorder, add bulk actions
• Rewrite SourceDirectoryOverlay — add proper tab ARIA roles, add search within tiers, add dynamic data loading

26.5 Nyx Overlays#

• Rewrite SkyMapOverlay — replace hardcoded SVG with real interactive star chart (canvas/WebGL), add geolocation, add zoom/pan, add constellation toggle that actually works
• Rewrite NightlyHighlightsOverlay — add responsive sidebar layout (stacked on mobile), add real astronomical data, add ARIA live regions for detail changes
• Rewrite EventCalendarOverlay — add real dates (not hardcoded strings), add iCal export, add timezone awareness, add calendar view option

27. Bug Fixes (From Deep Dive Audit)#

27.1 Code Bugs#

• Fix GoalsOverlay.tsx: Rename setNewGoalTile → setNewGoalTitle throughout file
• Fix GoalsOverlay.tsx: Replace Date.now() ID generation with UUID or crypto.randomUUID()
• Fix DomainLaunchFailureTelemetry.tsx: Add proper dependency array [domainId, source] to useEffect
• Fix error-monitoring.ts: Fix sampling logic — Math.random() > sampleRate should be Math.random() < sampleRate
• Fix UniversalSearchPanel.tsx: Complete getBaseRoutePath() to handle all domain cases (not just return /)
• Fix NotificationsCenterPanel.tsx: Move now = Date.now() inside component (currently at module level, becomes stale)
• Fix DailyCheckInOverlay.tsx: Implement actual save logic (comment says "Save logic would go here")

27.2 Non-functional Buttons#

• Fix ArticleReaderOverlay.tsx: Add onClick handlers to "Save" and "Share" buttons
• Fix SessionPlayer.tsx: Make forward/rewind buttons functional (currently decorative)
• Fix SkyMapOverlay.tsx: Make "Constellations: On" and "Grid: Off" buttons functional (currently decorative)
• Fix EventCalendarOverlay.tsx: Make "Add to Calendar" buttons functional (currently decorative)

27.3 Component Quality#

• Refactor ProfileSettingsPanel.tsx: Split 800+ line monolith into sub-components (BillingSection, PrivacySection, PreferencesSection, DataRightsSection)
• Remove all hardcoded demo data from ProfileSettingsPanel (dummy payment methods, fake brand-flip logic)
• Replace hardcoded CSS selectors in AccessibilityShell.tsx (.searchInputWrap input) with refs or IDs
• Remove arbitrary 520ms delay in DomainStartupGate.tsx or replace with actual loading detection
• Add focus trap to QuickActionsTrayPanel modal
• Add Escape key handler to QuickActionsTrayPanel modal
• Fix ReadingQueueOverlay.tsx: Pass article data to openReader() callback (currently passes nothing)
• Remove or replace all stopPropagation() calls with proper event architecture

28. Internationalization (i18n)#

• Select and integrate i18n library (next-intl recommended for Next.js App Router)
• Create translation namespace structure per domain (shell, tara, arete, veritas, nyx)
• Extract all user-facing strings from components into translation keys
• Create English translation files as the base language
• Add language detection from browser preferences
• Add language switcher in profile settings
• Add RTL layout support for Arabic/Hebrew locales
• Add date/time formatting utilities (locale-aware)
• Add number formatting utilities (locale-aware)
• Add pluralization rules per language
• Add currency formatting for subscription/payment displays

29. CI/CD & DevOps#

• Create GitHub Actions workflow for e2e tests (run Playwright on PR)
• Create GitHub Actions workflow for Lighthouse CI (performance budgets on PR)
• Create GitHub Actions workflow for deployment (staging and production)
• Add visual regression testing workflow (Percy, Chromatic, or similar)
• Add bundle size monitoring (bundlewatch or similar)
• Add dependency vulnerability scanning (Snyk, Dependabot)
• Add source map upload to error monitoring service
• Create staging environment configuration
• Create production environment configuration
• Add deployment rollback procedure documentation

30. Mobile App Parity#

Features that exist in the mobile app but not in the web app:

• Add recommendation carousel (mobile has this via /v1/recommendations)
• Add full notification preferences management (mobile has per-domain granularity)
• Add push notification registration for web (/v1/device-tokens with web-push platform)
• Add A/B testing framework integration (experimentation/ab-framework)
• Add feature flag system integration (experimentation/feature-flags)
• Add runtime configuration provider (load config from API on startup)
• Add performance telemetry (app startup timing, route transition timing)
• Add global offline banner (mobile has GlobalOfflineBanner.tsx)
• Add offline queue provider (mobile has offline-provider.tsx)
• Add deep link hydration with full navigation state restore (mobile has useDeepLinkHydration)
• Add crash reporting integration (mobile has crash-reporting.ts)
• Add reduced motion preference detection (mobile has useReducedMotionPreference)

Summary Statistics#