Expo App Architecture
Relevant source files
The following files were used as context for generating this wiki page:
The Expo mobile application within the Kocteau repository is currently an "intentionally future-facing" placeholder designed to mirror the established web platform's product direction. While the web application remains the primary source of truth, the mobile architecture is structured to transition into a production-ready state by sharing domain contracts, tokens, and business logic with the web core.
The architecture emphasizes parity with the web experience, focusing on a dark, editorial aesthetic and a music-centric discovery loop. It utilizes a modern React Native stack centered around Expo, leveraging file-based routing and a shared data layer to ensure consistency across platforms.
Sources: CONTRIBUTING.md:4-5, apps/mobile/README.md:1-12, apps/mobile/lib/roadmap.ts:5-8
Core Tech Stack
The mobile application is built on the Expo framework, utilizing several key libraries for navigation, UI, and data management.
| Category | Technology / Library | Purpose |
|---|---|---|
| Framework | expo (~54.0.35) | React Native framework and tooling |
| Routing | expo-router (~6.0.24) | Native file-based routing |
| UI Engine | react-native (0.81.5) | Native component primitives |
| Data Fetching | @tanstack/react-query | Server state management and caching |
| Navigation | @react-navigation/* | Bottom tabs and native navigation elements |
| Styling/Animation | react-native-reanimated | High-performance animations |
| Image Handling | expo-image | High-performance image loading and caching |
Sources: apps/mobile/package.json:28-56
Routing and Navigation
The mobile app employs expo-router for file-based routing, organizing screens into a logical hierarchy that matches the web application's structure.
Layout Structure
The application uses a directory-based routing system:
(tabs)/: Contains the primary navigation surfaces (e.g., the Feed).review/[id].tsx: Dynamic route for detailed music review views.track/[id].tsx: Dynamic route for specific music track or entity pages.u/[username].tsx: Dynamic route for user profiles.modal.tsx: A global modal for informative content like the migration roadmap.
Navigation Flow
The following diagram illustrates the primary user navigation paths within the mobile shell.
This diagram shows the relationship between the main feed and the dynamic detail routes, highlighting the central role of the feed in discovery.
Sources: apps/mobile/app/(tabs)/index.tsx, apps/mobile/app/review/[id].tsx, apps/mobile/app/track/[id].tsx, apps/mobile/app/u/[username].tsx, apps/mobile/app/modal.tsx
Component Architecture
Mobile UI components are designed to be "product-aligned," reusing patterns from the web feed while adapting to native constraints.
Shared UI Patterns
- Screen Component: A base
Screenwrapper (imported from@/components/kocteau/screen) provides consistent layout, scrolling behavior, and theme integration across all routes. - Card Grammar: The application uses specific card variants—
FeedReviewCard,ReviewPageCard,TrackReviewCard, andProfileReviewCard—which maintain a consistent "grammar" or visual language regardless of the context. - Theming: Custom hooks like
useKocteauThemeprovide access to a centralized theme object containing brand-specific colors, typography, spacing, and radii.
Sources: apps/mobile/app/review/[id].tsx:7-11, apps/mobile/app/(tabs)/index.tsx:4-9, apps/mobile/app/track/[id].tsx:12-25
Migration Roadmap and Future Directions
The mobile app is currently in a foundational phase, with a clear three-phase roadmap to reach parity with the web application.
The roadmap visualizes the sequential progression from building architectural scaffolding to integrating live data and finally unifying the user experience across platforms.
Sources: apps/mobile/lib/roadmap.ts:1-40, apps/mobile/app/modal.tsx:18-20
Planned Features
According to the migration strategy, the mobile application will eventually integrate the following core web features:
- OTP-first Auth: Integration with Supabase Auth for email-based login.
- Onboarding: Profile and taste-based onboarding flows.
- For You Feed: Live personalized recommendations.
- Optimistic Engagement: Support for likes, bookmarks, and comments with immediate UI updates using React Query.
Sources: apps/mobile/README.md:16-21, apps/mobile/lib/roadmap.ts:19-21
Project Utility: Reset Script
The mobile directory includes a specialized utility script, reset-project.js, which allows developers to clear the current placeholder implementation and start from a blank Expo slate.
- Functionality: It deletes or moves the
/app,/components,/hooks,/scripts, and/constantsdirectories to an/app-examplebackup. - Initialization: It generates a new
/appdirectory with basicindex.tsxand_layout.tsxfiles to serve as a clean starting point.
Sources: apps/mobile/scripts/reset-project.js:1-93
Conclusion
The Expo app architecture in Kocteau is a strategic extension of the web platform, currently focused on structural alignment and visual consistency. By utilizing a shared roadmap and common domain contracts, the project ensures that the eventual mobile experience will be a seamless, native realization of the core music discovery loop established on the web.
Sources: apps/mobile/README.md:23-24, apps/mobile/lib/roadmap.ts:31-33