A React Native + Expo app for managing shared expenses and household tasks with roommates.
- 🔐 User authentication (login/register)
- 🏠 Multi-house support with invite codes
- 💰 Expense tracking and balance management
- 🛒 Collaborative shopping lists with recurring items
- 💸 Payment recording between roommates
- 📱 Mobile-first design with WhatsApp-inspired UI
- 🎨 Customizable user and house colors/images
- React Native with Expo
- TypeScript for type safety
- React Navigation for navigation (bottom tabs + stack)
- Axios for API calls
- AsyncStorage for local data persistence
- Expo Vector Icons for icons
- React Native Paper/Elements for UI components
src/
├── components/ # Reusable UI components
│ ├── UI/ # Basic UI components (Button, Input, Card, Avatar)
│ └── Forms/ # Form-specific components
├── screens/ # Screen components
│ ├── Auth/ # Login, Register, Join/Create House
│ ├── Home/ # Main dashboard
│ ├── ShareCost/ # Expense splitting flow
│ └── Profile/ # User profile and settings
├── navigation/ # Navigation configuration
├── services/ # API service layer
├── context/ # React context providers
├── types/ # TypeScript type definitions (by feature)
├── constants/ # App constants (by feature)
├── utils/ # Utility functions
└── assets/ # Images, icons, etc.
- Node.js (v16 or later)
- npm or yarn
- Expo CLI:
npm install -g @expo/cli - iOS Simulator (Mac) or Android Studio
- Install dependencies:
npm install- Set up environment configuration:
npm run setup-env- Start the development server:
npm start- Run on device/simulator:
# iOS Simulator
npm run ios
# Android Device/Emulator
npm run android
# Web Browser
npm run web
# Physical devices (Android/iOS) via tunnel
npm run dev:tunnelRun the automated environment setup:
npm run setup-envThis command will:
- 🔍 Automatically detect your computer's IP address
- 📝 Create
.env.localwith the correct configuration - ✅ Configure the app to work on both iOS simulator and Android devices
- 🚀 Get you ready to develop immediately
If you prefer to configure manually:
- Copy the example environment file:
cp .env.example .env.local- Get your computer's IP address:
# macOS/Linux
ifconfig | grep "inet " | grep -v 127.0.0.1
# Windows
ipconfig- Update
.env.localwith your settings:
# For local development with physical devices (Android/iOS via Expo Go)
EXPO_PUBLIC_API_BASE_URL=http://YOUR_COMPUTER_IP:3001
# For iOS simulator only (if you don't need Android device support)
EXPO_PUBLIC_API_BASE_URL=http://localhost:3001.env.example- Template (committed to git).env.local- Your local development config (gitignored).env.production- Production config (gitignored)
Important: Never commit .env.local or .env.production as they may contain secrets in the future.
For Physical Devices (Android/iOS via Expo Go):
- 📶 Your computer and mobile device must be on the same WiFi network
- 🏠 The network IP configuration (set by
npm run setup-env) only works when both devices share the same local network - 🌐 If on different networks, use tunnel mode:
npm run dev:tunnel(slower but works across networks)
Main app settings are in src/constants/app.ts and app.json.
- Primary: #FF6B35 (Orange for Share Cost button)
- Secondary: #6366F1 (Blue)
- Success: #10B981 (Green)
- Card Headers: Pastel colors for different sections
- Balances: Light Yellow (#FEF3C7)
- Shopping: Light Green (#D1FAE5)
- Activity: Light Blue (#DBEAFE)
- Bottom Tab Navigation: Home, Share Cost (FAB), Profile
- Stack Navigation: For deeper flows like expense splitting
- WhatsApp-style Home: Sticky header with household info + card-based content
- Login/Register screens with form validation
- JWT token management with AsyncStorage
- Auto-login on app restart
- Household header with avatar and member count
- Cards for Balances, Shopping List, Recent Activity
- Real-time updates (placeholder for WebSocket integration)
- Choose between shopping receipt split or manual expense
- Step-by-step expense splitting with preview
- Integration with shopping list items
- User profile management
- House list with join/create options
- Settings and preferences
All API calls go through src/services/ with proper error handling:
authService.ts- Authentication endpointsapi.ts- Axios configuration with interceptors
Features:
- Automatic JWT token attachment
- Token refresh on 401 errors
- Request/response logging
- Offline handling (future)
- Authentication: React Context (
AuthContext) - Local Storage: AsyncStorage for persistence
- API State: Individual service calls (can be upgraded to React Query)
# Build for app stores
eas build --platform all
# Local builds
npm run build:ios
npm run build:androidThe app is configured for deployment to both iOS App Store and Google Play Store:
- Bundle ID:
com.roomiesync.app - App name: "RoomieSync"
- Required permissions: Camera, Photo Library (for receipts/profiles)
- Create types in
src/types/[feature].ts - Add constants in
src/constants/[feature].ts - Implement API service in
src/services/[feature]Service.ts - Create UI components in
src/components/ - Build screens in
src/screens/[feature]/ - Update navigation as needed
- Use TypeScript for all new code
- Follow React Native best practices
- Use feature-based organization
- Prefer functional components with hooks
- Extract constants and avoid magic numbers
- Real-time updates with WebSocket
- Push notifications
- Receipt photo scanning with OCR
- Biometric authentication
- Dark mode support
- Internationalization
- Offline mode with sync
- Chat/messaging between roommates
- Follow the existing code structure
- Add types for all new features
- Update this README for significant changes
- Test on both iOS and Android before submitting
The backend API documentation is available at http://localhost:3001/api when running the NestJS backend.