Overview

I rebuilt the Earworm mobile app as a Web Native project that runs smoothly on the web (Vite dev server) and compiles to native via Capacitor. The result is a mobile‑first React application with an iOS‑style interface, social features, and service integrations, designed for quick iteration in the browser and seamless deployment to native.

Goals

- Modernize the stack to React + Vite + TypeScript with Capacitor for native packaging.

- Preserve and enhance core features: notifications, music service management, proximity discovery, and background scanning simulation.

- Deliver a mobile‑first UI/UX with social profiles, friends list, and bottom tab navigation.

- Improve developer experience, reliability, and debuggability.

Tech stack

- React 19, TypeScript 5, Vite 7 for fast DX and HMR.

- Capacitor 7 (iOS project included) with plugins (Device, Geolocation, Local Notifications, Network, Preferences, Share, Toast).

- Modular service layer (Spotify, Apple Music, SoundCloud, Musi) orchestrated by a MusicServiceManager.

- Context-based state management: AuthContext, MusicContext, ProximityContext, RealtimeContext.

- Mobile‑first CSS with safe‑area support, iPhone‑frame desktop simulation, and accessible UI patterns.

Key features

- Authentication: Mock/demo flow with persisted session; easy to swap for real backend auth.

- Music integrations: Unified manager for connecting services and fetching/searching tracks.

- Proximity discovery: Mock background scanning that surfaces nearby listeners; privacy‑first display shows “Nearby” instead of exact meters.

- Realtime layer: Simulated realtime messages for user status and social activity.

- Notifications: In‑app toasts + production‑gated browser push scaffolding; Capacitor Local Notifications available for native builds.

- Social UI: Friends and Profile screens matching provided designs, including emoji reactions and music activity.

- Navigation: Bottom tab bar (Home, Discover, Friends, Profile, Settings) with mobile touch affordances.

Notable implementation details

- Strict mobile‑first layout, safe‑area insets, and touch optimizations.

- Desktop iPhone‑frame simulation for accurate visual QA during web development.

- Environment handling: Replaced process.env with Vite import.meta.env across services for correctness.

- Dev ergonomics: Disabled service worker in dev and auto‑unregister to avoid caching “white screen” issues; added visible boot placeholder and a Debug HUD to verify render pipeline.

- Error resilience: ErrorBoundary + fallback UI to prevent hard blanks and surface runtime failures.

Challenges and solutions

- White/blank screen in dev: Root cause was legacy process.env usage and dev SW caching. Fixed by switching to import.meta.env and disabling/unregistering SW in dev, plus adding an always‑visible boot marker and logs to confirm mount.

- Navigation not visible on desktop: CSS media rule hid the bottom bar ≥768px; updated styles so the tabs are always visible during desktop simulation.

- Privacy concerns around proximity: Removed exact distance strings (e.g., “5m away”) and replaced with “Nearby”; kept distance only in internal mocks.

- Type and import drift: Standardized exports for services/contexts and resolved TypeScript issues in components.

Outcomes

- A working Web Native app that runs at localhost via Vite and is ready for Capacitor iOS packaging.

- Restored and enhanced core features with a modular, testable architecture and clear provider boundaries.

- Social/profile and friends list implemented per screenshots with mobile‑first polish and emoji interactions.

What’s next

- Hook AuthContext to a real backend (OAuth or custom auth) and wire live tokens to MusicServiceManager.

- Replace mock proximity and realtime with secure, privacy‑preserving implementations (BLE, WebSocket, or backend events).

- Expand test coverage and add E2E flows for navigation and auth.

- Ship to TestFlight via Capacitor iOS build pipeline.