# OSHUN Web App — Comprehensive Gap Analysis & UI Audit **Date**: 2026-02-21 **Scope**: `apps/oshun/web`, `apps/oshun/bff`, domain libraries (`libs/tara`, `libs/arete`, `libs/veritas`, `libs/nyx`), shared libraries (`libs/shared`, `libs/psyche`) --- ## Executive Summary The OSHUN web app is a Next.js 14+ application that serves as the unified shell for four domains: **Tara** (meditation), **Arete** (personal growth), **Veritas** (news/research), and **Nyx** (astronomy). The web app currently exposes only a surface-level fraction of the capabilities that exist in the underlying domain libraries. Across all four domains, the libraries contain **hundreds of modules** — sophisticated AI coaching, gamification engines, habit systems based on published behavioral science frameworks, news verification agents, astronomy catalogs, and more — yet the web UI presents each domain as little more than a static card layout with hardcoded mock data. Additionally, the UI suffers from significant design quality issues: inconsistent visual hierarchy, amateurish component styling (inline styles, flat layouts, no iconography, no micro-interactions), and a lack of the polish expected from a professional product. --- ## Part 1: Domain Feature Gap Analysis ### 1.1 Tara — Meditation & Mindfulness **What the web app currently shows:** - A hero section with hardcoded stats (streak, today, weekly, sessions) - A featured session card with title/description/tags - A static session library grid (6 sessions) - A courses list with 3 hardcoded courses + progress bars - Quick actions (resume, breathwork, courses, favorites) - Two overlay components: BreathworkTimer (functional box breathing) and SessionPlayer (basic timer) **What exists in `libs/tara/` but is NOT exposed:** | Library | Description | Status in UI | | ----------------------- | -------------------------------------- | ------------ | | `@tara/analytics` | 10+ analytics modules (usage, engage) | Not exposed | | `@tara/content` | Content management system | Not exposed | | `@tara/database` | Domain-specific data models | Not exposed | | `@tara/monitoring` | Health and performance monitoring | Not exposed | | `@tara/features` | Feature flagging system | Not exposed | | `@tara/ui` (full suite) | Complete component library with themes | Partially | **Specific feature gaps:** 1. **No real session library** — The session list is hardcoded. No search, filter, category browse, or sort controls. 2. **No course detail view** — Clicking a course does nothing. No lesson list, no progress within lessons. 3. **No favorites system** — The "Favorites" quick action exists but there's no favorites view. 4. **No session history** — No way to see past sessions, completed courses, or duration trends. 5. **No instructor profiles** — Sessions mention "Sage" but there's no instructor detail. 6. **No timer customization** — The breathwork timer only does 4-4-4-4 box breathing. No alternate patterns (4-7-8, Wim Hof, custom). 7. **No ambient audio** — No background soundscapes or audio accompaniment. 8. **No daily meditation reminder/prompt** — Unlike Arete's check-in, Tara has no morning/evening mindfulness prompt. 9. **No meditation journal** — No post-session reflection or notes. 10. **No community/social features** — No shared sessions or group meditation. 11. **No streak detail** — The "7 days" streak has no breakdown, no calendar view, no streak freeze/recovery. ### 1.2 Arete — Daily Growth & Personal Development **What the web app currently shows:** - Dashboard stats (goals, habits, streak, journal entries) - Daily check-in with rotating prompts - Weekly summary (static) - Goals list with progress bars (4 goals) - Habit tracker with toggle (6 habits) - Journal entries list (3 entries) - AI coaching insights (3 static strings) - Overlays: DailyCheckInOverlay, JournalOverlay, GoalsOverlay **What exists in `libs/arete/` but is NOT exposed:** | Library | Description | Status in UI | | --------------------- | ----------------------------------------- | ------------ | | `@arete/ai-coach` | Conversational AI coaching (CBT, goals) | Not exposed | | `@arete/habits` | 10-module habit engine (Atomic Habits) | ~5% exposed | | `@arete/goals` | Goal management and alignment | ~10% exposed | | `@arete/gamification` | Points, badges, leaderboards, challenges | Not exposed | | `@arete/journal` | Journal with analytics, sentiment, NLP | ~5% exposed | | `@arete/balance` | Work-life balance assessment | Not exposed | | `@arete/affirmations` | Daily affirmations system | Not exposed | | `@arete/time` | Time management (Pomodoro, time blocking) | Not exposed | | `@arete/vision` | Vision statement and long-term planning | Not exposed | | `@arete/seven-habits` | Covey's 7 Habits framework | Not exposed | **Specific feature gaps:** 1. **AI Coach is invisible** — The "AI coaching insights" section shows 3 static strings. The `@arete/ai-coach` library has conversational coaching with CBT techniques, personalized recommendations, pattern recognition, and smart notifications — none of which are surfaced. 2. **Habits lack depth** — The habit tracker is a simple toggle list. The library supports Atomic Habits cue-routine-reward loops, habit stacking, Four Laws of Behavior Change, celebration/reinforcement mechanics, identity-based habits, keystone habits, and analytics dashboards. 3. **No gamification** — The `@arete/gamification` library provides points, badges, leaderboards, challenges, and reward mechanics. Zero of this is surfaced. 4. **No affirmations** — A complete affirmation system exists in the library. 5. **No time management** — Pomodoro timer, time blocking, and calendar analysis features exist but aren't shown. 6. **No vision board** — Long-term vision statements and goal planning are in the library. 7. **No 7 Habits integration** — A full implementation of Covey's framework exists. 8. **No work-life balance tools** — Energy management, recovery tracking, and balance assessment are built but hidden. 9. **No journal analytics** — The library has sentiment analysis, emotion detection, topic extraction — but the UI just shows text excerpts. 10. **No goal creation** — Users can't create, edit, or archive goals. The GoalsOverlay is basic. 11. **No habit creation** — Can't add new habits. The list is hardcoded. 12. **No data visualization** — No charts for trends, mood graphs, or habit completion heatmaps. ### 1.3 Veritas — Truth-First News & Research **What the web app currently shows:** - Trending claims list with confidence badges (5 items) - Reading queue (3 items) - Topic alerts (4 topics) - Source trust tiers (3 tiers) - Overlays: ArticleReaderOverlay, ReadingQueueOverlay, SourceDirectoryOverlay **What exists in `libs/veritas/` but is NOT exposed:** | Library | Description | Status in UI | | ----------------------------- | ----------------------------------------- | ------------ | | `@veritas/agents` (10+) | Journalism, fact-check, QA, social agents | Not exposed | | `@veritas/bias-detection` | Linguistic and coverage bias analysis | Not exposed | | `@veritas/fact-checking` | Claim verification workflow | Not exposed | | `@veritas/knowledge-graph` | Entity relationship management | Not exposed | | `@veritas/rag` | Retrieval-augmented generation | Not exposed | | `@veritas/story-clustering` | Automatic story correlation | Not exposed | | `@veritas/ab-testing` | Experimentation framework | Not exposed | | `@veritas/content-class` | Multi-dimensional content tagging | Not exposed | | `@veritas/newsletter` | Newsletter generation | Not exposed | | `@veritas/live-stream` | Live event coverage | Not exposed | | `@veritas/payments` | Paywall and subscription | Not exposed | | `@veritas/recommendations` | Content recommendation engine | Not exposed | | `@veritas/regional` | Ghana-specific NLP and political data | Not exposed | | `@veritas/article-versioning` | Article diff tracking | Not exposed | | `@veritas/author-profiles` | Author verification and profiles | Not exposed | | `@veritas/seo` | Search engine optimization | Not exposed | **Specific feature gaps:** 1. **No claim detail view** — Clicking a claim opens a generic overlay, not a detailed verification page showing evidence chains, sources, and confidence breakdown. 2. **No bias indicators** — The library has sophisticated bias detection, but articles show no bias warnings or political alignment markers. 3. **No fact-checking workflow** — Users can't submit claims for verification or follow verification trails. 4. **No knowledge graph** — Entity relationships between stories, sources, and claims are available but not visualized. 5. **No article versioning** — The library tracks article changes over time; this isn't shown. 6. **No author profiles** — No author verification status, credentials, or publication history. 7. **No story clustering** — Related stories aren't grouped together. 8. **No newsletter** — Users can't subscribe to or generate topic digests. 9. **No live event coverage** — Real-time story tracking isn't surfaced. 10. **No full-text search** — The reading queue has no search functionality. 11. **No bookmarking with annotations** — Can't add notes to saved articles. 12. **No content categories/taxonomy** — Only 4 topic alerts with no browse UI. 13. **No regional/local news** — Ghana-specific capabilities aren't surfaced. 14. **No "queue" button works correctly** — The queue toggle on trending claims uses local state only; it doesn't persist. ### 1.4 Nyx — Night Sky Observatory **What the web app currently shows:** - Tonight's highlights (3 items) - Sky conditions panel (moon, sunset, Bortle, transparency, seeing) - Upcoming events calendar (5 items) - Observation log (3 entries) - PWA install prompt for sky alerts - Overlays: NightlyHighlightsOverlay, SkyMapOverlay, EventCalendarOverlay **What exists in `libs/nyx/` but is NOT exposed:** | Library | Description | Status in UI | | --------------------- | ---------------------------------------- | ------------ | | `@nyx/realtime-solar` | Solar activity, aurora forecasts | Not exposed | | `@nyx/realtime-neo` | Near-Earth object tracking & impact risk | Not exposed | | `@nyx/time-travel` | Historical and future sky calculations | Not exposed | | `@nyx/education` | Curriculum and learning modules | Not exposed | | `@nyx/catalogs` (17+) | Specialized astronomy catalogs | Not exposed | | `@nyx/coordinates` | Multiple coordinate system support | Not exposed | | `@nyx/analysis` | Spectral and orbital analysis | Not exposed | | `@nyx/audio` | Sonification (data to sound) | Not exposed | | `@nyx/visualization` | Multiple rendering backends | Not exposed | | `@nyx/integrations` | External data source connections | Not exposed | **Specific feature gaps:** 1. **No interactive star map** — The "Sky map" overlay exists but is a placeholder. No canvas-based or WebGL star chart. 2. **No solar activity dashboard** — Aurora forecasts, solar wind data, CME alerts exist in the library. 3. **No Near-Earth Object tracker** — Impact risk assessment and NEO tracking are built but invisible. 4. **No time travel/historical view** — "What did the sky look like on [date]?" is supported by the library. 5. **No education modules** — Guided astronomy lessons exist in `@nyx/education`. 6. **No deep catalog access** — 17+ specialized catalogs (Messier, NGC, IC, etc.) are inaccessible. 7. **No observation log creation** — Users can't add new observations; the log is hardcoded. 8. **No sonification** — Converting astronomical data to sound is a unique feature that exists but isn't exposed. 9. **No equipment profile** — No telescope/binocular setup for personalized visibility recommendations. 10. **No location awareness** — Sky conditions are hardcoded. No geolocation for accurate sunset/rise times. 11. **No moon phase detail** — Just a text string; no visual lunar phase diagram. 12. **No constellation viewer** — Multi-cultural constellation databases exist. 13. **No light pollution map** — Bortle class is shown as a number; no visual map. --- ## Part 2: Shared Library Capabilities NOT Surfaced ### 2.1 @oshun/ai — AI/LLM Platform Provides quality routing, batch processing, prompt compression, A/B testing, sanitization, debugging, local LLM support, and budget management. **None of this is surfaced in any domain UI** for user-facing AI interactions. ### 2.2 @oshun/websocket — Real-time Features Room management, presence tracking, message queuing, and horizontal scaling are built. **The web app has zero real-time features** — no live updates, no presence indicators, no collaborative sessions. ### 2.3 @oshun/event-bus — Distributed Events Type-safe event publishing, dead letter queues, event persistence and replay. **Not used for any user-facing live feed or event stream.** ### 2.4 @psyche/ — AI Agent Platform (99+ libraries) The Psyche platform contains: - **Memory systems** — Hierarchical memory, persistence, retrieval, consolidation, archival - **Avatar/Expression** — FACS expressions, lipsync, emotion engine, micro-expressions - **Engagement** — Multi-dimensional scoring, attention tracking, anomaly detection - **Screen analysis** — 82+ analyzers for presentations, documents, spreadsheets, whiteboards - **Conversational** — Dialogue management, TTS, voice streaming, turn-taking - **Knowledge** — Context-aware retrieval, ingestion, semantic search - **Safety** — Action safety checks, behavior coordination, uncanny valley detection **Zero of these are exposed in the web app.** No AI assistant, no avatar, no voice interaction, no intelligent content analysis. --- ## Part 3: UI/UX Design Audit ### 3.1 Critical Design Issues #### **A. No Icon System** The entire app uses zero icons. Navigation ("Home", "Explore", "Activity", "Profile") is text-only. Domain quick actions are text-only buttons. There are no visual indicators for states (completed, in-progress, locked). This immediately makes the app feel like a developer prototype rather than a shipped product. #### **B. Flat Visual Hierarchy** Every section looks the same: a dark bordered rectangle with a heading and text. There's no visual differentiation between: - Primary actions vs. secondary - Important content vs. supplementary - Active/current state vs. future/past - Different content types (video, audio, text, interactive) #### **C. Inline Styles on Interactive Components** The `BreathworkTimer`, `SessionPlayer`, and overlay components use inline `style={{...}}` objects throughout. This results in: - Inconsistent styling between overlays and the main surface - No hover/focus/active state management - No responsive behavior - No animation system integration #### **D. No Micro-interactions or Feedback** - Button clicks have no visual feedback beyond cursor change - Habit toggles switch instantly with no transition - No loading skeletons; pages are either fully loaded or empty - No success/error toasts - No confetti/celebration for achievements or milestones - Progress bars are static CSS widths with no animation #### **E. No Visual Brand Identity** - No logo anywhere in the app - No brand typography (using system "Avenir Next" / "Segoe UI") - No illustration or imagery - No empty state illustrations - Domain surfaces lack unique visual identity beyond accent color #### **F. Amateur Navigation Pattern** The `ShellRouteNavigator` is a row of small pill buttons at the top. This pattern: - Lacks standard webapp conventions (sidebar, top navbar with logo) - Has no visual weight or hierarchy - Doesn't show the current user or any global state - Has no breadcrumb or back navigation from domain surfaces - No mobile-responsive bottom tab bar equivalent #### **G. Color Monotony** Despite the dark theme being an intentional choice, the execution lacks depth: - Almost every surface uses the exact same `rgba(15, 23, 42, 0.8)` background - Border colors are nearly identical across all components - No gradient usage within cards or sections - Text hierarchy relies solely on opacity (`#f8fafc`, `#cbd5e1`, `#7c93b3`) — no size or weight variation enough #### **H. Empty State Handling** When data is unavailable: - The BFF fetch silently fails and shows hardcoded fallback data - No "No data yet" empty states - No onboarding guidance for new users - No loading indicators during fetches ### 3.2 Responsive Design Issues 1. **KPI grid breaks on mobile** — `grid-template-columns: repeat(4, minmax(0, 1fr))` doesn't wrap, so KPI tiles compress to unreadable sizes on small screens. 2. **Split grids don't stack** — Two-column layouts remain side-by-side below 768px. 3. **Domain surfaces lack mobile optimization** — Stats grids, quick action rows, and list items don't reflow. 4. **No breakpoint-specific typography** — The `clamp()` on the title is the only responsive type scale. 5. **Overlays are not mobile-friendly** — Fixed position overlays don't account for viewport height variations or safe areas. ### 3.3 Accessibility Gaps While the app has basic ARIA labels and keyboard shortcuts, several gaps remain: 1. **No focus-visible styles** — Keyboard navigation produces no visible focus indicator. 2. **Color-only information** — Confidence badges (green/yellow/red) and visibility indicators convey meaning through color alone with no pattern or text alternative. 3. **No reduced motion respect** — `@media (prefers-reduced-motion)` queries exist for the overall shell but animations in `BreathworkTimer` use inline styles that ignore this preference. 4. **Habit toggle is div, not input** — The habit row uses `onClick` on an `
` with no `role="checkbox"` or keyboard handling. 5. **No error announcements** — Failed BFF requests don't announce to screen readers. --- ## Part 4: Architecture & Code Quality Issues ### 4.1 Hardcoded Mock Data Everywhere Every surface component (`TaraSurface`, `AreteSurface`, `VeritasSurface`, `NyxSurface`) initializes with large hardcoded constant arrays that serve as fallback data when the BFF is unavailable. This: - Creates the illusion of a working app that is actually static - Means users see fake metrics (streak "7 days", sessions "42 total") - Masks data flow issues ### 4.2 Hardcoded BFF URL All domain surfaces use `http://localhost:4010` directly. No environment variable, no API client abstraction. This will break in any non-local environment. ### 4.3 Hardcoded Auth Token The Bearer token `dev.eyJzdWIiOiJ1MTIzIiwic2NvcGVzIjpbImRvbWFpbjoqIl19` is embedded directly in every fetch call. No auth provider, no token refresh, no session management. ### 4.4 No State Management Each surface manages its own local state with `useState`. There's no shared state between surfaces, no cache, no optimistic updates, no state persistence. Navigating away from a domain and back resets all state and re-fetches. ### 4.5 No Error Handling Every `fetch` call catches errors with `console.error`. No user-facing error states, no retry logic, no offline handling despite the PWA setup. ### 4.6 No Data Fetching Layer No SWR, React Query, or equivalent. Each component manually manages fetch lifecycle with `useEffect` + `useState` + `try/catch`. ### 4.7 No Component Library Every component is a one-off. There's no shared ``, `