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:

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:

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:

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:

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 <article> 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 <Card>, <Button>, <Badge>, <ProgressBar>, <StatTile>, <OverlaySheet>, or <EmptyState> component. The same patterns are copy-pasted with slight variations across all surfaces.

Part 5: Recommendations Priority Matrix#

Part 5: BFF Endpoint Gap Analysis (Deep Dive)#

The BFF service contains 130+ fully implemented endpoints across 7 major subsystems. The web app uses fewer than 10 of these. The following entire subsystems exist in the backend with ZERO web UI integration:

5.1 Achievement & Social Accountability System (17+ endpoints)#

The BFF has a complete AchievementEngine with:

• Achievement definitions, categories, tiers, domains
• User achievement tracking with unlock status
• Achievement evaluation and auto-unlock
• Unacknowledged achievement notifications
• Accountability partnerships — invite, accept, decline, end, check-in, encourage, health analysis
• Challenge system — templates, join, record daily progress, drop, leaderboards
• Partnership insights with engagement scoring

Impact: Users have no way to earn achievements, join challenges, or connect with accountability partners despite the entire backend being production-ready.

5.2 Routine Automation System (18+ endpoints)#

A complete RoutineEngine supports:

• Routine templates (morning, evening) with cross-domain steps
• Custom routine creation from templates
• Step-by-step routine execution (start, advance, pause, resume, abandon)
• Active execution tracking
• Execution history with statistics
• Scheduling (daily, weekdays, weekends, custom days)
• Multi-domain integration (Tara + Arete steps in one routine)

Impact: The "Daily Plan" on the home page is hardcoded text. The backend has a fully operational routine system that could power dynamic, personalized daily plans.

5.3 Voice-First Assistant System (4 endpoints)#

An AssistantEngine provides:

• Session management (create, message, list, end)
• Voice and text input modes
• Domain-aware context (Tara, Veritas, Nyx, Arete)
• Domain-specific tool integration (start sessions, save articles, log observations, check goals)

Impact: Zero AI assistant integration in the web app despite backend support.

5.4 Wearable Companion System (28 endpoints)#

A WearableEngine manages:

• Device registration (watchOS, WearOS, Fitbit, Garmin)
• Preferences (haptic intensity, quiet hours, streak alerts)
• Complications (watch face widgets)
• Smart reminders with dismiss/snooze
• Daily and weekly summary generation
• Cross-domain streak comparison
• Glanceable quick-reference summaries

Impact: Wearable features may seem non-web, but the stats, summaries, and streak comparisons could all be surfaced in the web dashboard.

5.5 Desktop Application System (30+ endpoints)#

A DesktopEngine provides:

• Focus mode toggle
• Window management with roles
• Global and app shortcuts
• Deep link handling and building
• Widget sidebar (add, remove, refresh)
• System snapshot and lifecycle events
• Update status and preferences

Impact: Desktop features like focus mode, widgets, and shortcuts could all be adapted for the web PWA.

5.6 Favorites Management (used minimally)#

• GET /v1/favorites — Tara favorites with pagination
• POST /v1/favorites/:meditationId — Add to favorites
• DELETE /v1/favorites/:meditationId — Remove from favorites

Impact: The web app's Tara surface has a "Favorites" quick action but no favorites view or management UI. The BFF is ready.

5.7 Recommendation Feedback (not used)#

• POST /v1/recommendations/feedback — Send signals (hide, less, more) for recommendations with optional reason

Impact: Users can't provide feedback on recommended content, preventing the recommendation engine from learning their preferences.

5.8 Session Audio (not used)#

• GET /v1/sessions/:sessionId/audio?quality=... — Stream meditation audio in standard, high, or lossless quality

Impact: The SessionPlayer component simulates playback with a timer but has no actual audio integration despite the BFF endpoint being ready.

Part 6: Component-Level Quality Audit (Deep Dive)#

6.1 Overlay Component Issues#

All 10 overlay components share these systemic problems:

Specific bugs found:

• GoalsOverlay.tsx: Variable typo setNewGoalTile (should be setNewGoalTitle) — persists throughout the file
• GoalsOverlay.tsx: Goal IDs generated with Date.now() — race condition possible
• DailyCheckInOverlay.tsx: Comment says "Save logic would go here" but no actual save endpoint is called
• ArticleReaderOverlay.tsx: "Save" and "Share" buttons have no onClick handlers
• SkyMapOverlay.tsx: Control buttons ("Constellations: On", "Grid: Off") are purely decorative — nothing toggles
• SessionPlayer.tsx: Forward/rewind buttons (↺ 15, 15 ↻) are non-functional
• SessionPlayer.tsx: No actual audio element — progress is simulated with setInterval
• ReadingQueueOverlay.tsx: openReader() callback passes no article data — reader doesn't know what to display
• NotificationsCenterPanel.tsx: now = Date.now() calculated at module level becomes stale in long sessions

6.2 Shell Component Issues#

• ProfileSettingsPanel.tsx: 800+ line monolith component — should be split into billing, privacy, preferences, and data rights sub-components
• ProfileSettingsPanel.tsx: Hardcoded dummy payment method creation with brand-flip logic (Visa → Amex alternation) for demo purposes
• UniversalSearchPanel.tsx: getBaseRoutePath() function is incomplete — returns just / for unknown domains (would break navigation)
• DomainStartupGate.tsx: Arbitrary 520ms delay before showing content with no explanation
• DomainLaunchFailureTelemetry.tsx: Missing dependency array on useEffect — runs on every render
• AccessibilityShell.tsx: Keyboard shortcut handler uses hardcoded CSS selector .searchInputWrap input — fragile if class names change
• QuickActionsTrayPanel.tsx: Modal has no focus trap, no escape key handler, backdrop has no keyboard-accessible close

6.3 State Management Issues#

• observability/error-monitoring.ts: Sampling logic appears backwards — Math.random() > sampleRate means higher sample rates capture FEWER errors
• profile/store.ts: Multiple module-level mutable state flags for hydration tracking — not thread-safe in concurrent React 18 rendering

Part 7: Production Readiness Gaps#

7.1 Missing Critical Files#

7.2 Security Header Gaps#

7.3 Missing Infrastructure#

• No i18n/localization — Zero internationalization setup. No translation files, language detection, or RTL support.
• No Next.js middleware — No auth guards, no redirect logic, no request logging.
• No cookie consent banner — Missing for GDPR compliance.
• No accessibility statement — Missing for WCAG compliance.
• No authenticated user onboarding — Marketing welcome pages exist, but there is no post-signup wizard (domain selection, preferences, notifications).
• No CI/CD workflows — No GitHub Actions for e2e tests, Lighthouse CI, or deployment.

7.4 Mobile App Feature Parity Gaps#

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

• Direct recommendation carousel from /v1/recommendations
• Full notification preferences management UI
• Push notification device token management
• Deep link hydration with full navigation state restore
• A/B testing framework integration
• Feature flag system integration
• Crash reporting with proper transport
• Runtime configuration provider
• Performance telemetry (app startup, route transitions)
• Offline queue provider with global offline banner

Part 8: Recommendations Priority Matrix (Updated)#

Conclusion#

The OSHUN web app is currently a thin shell sitting on top of an extraordinarily deep library and backend ecosystem. The mismatch between what exists (hundreds of sophisticated library modules, 130+ BFF endpoints across 7 subsystems, and a production-ready mobile app) and what users can actually interact with (static card layouts with hardcoded data, non-functional buttons, and inline-styled overlays) represents the single largest gap in the platform.

The backend is approximately 3x more feature-rich than what the web app exposes. Entire subsystems — achievements with social accountability, cross-domain routine automation, voice-first assistant, wearable companion, and desktop integration — are fully built but completely invisible to web users.

Beyond feature gaps, the app has critical production blockers: missing CSP and HSTS security headers, no error pages, no favicon, no middleware for auth guards, and no cookie consent for GDPR.

Addressing these gaps systematically — starting with security and infrastructure, then design system, then feature exposure — will transform this from a developer prototype into a professional, production-grade product.