A full-stack task management application built with React Native (Expo) frontend and NestJS backend.
- Authentication: JWT-based login/register system
- Task Management: Create, read, update, delete tasks
- Real-time Synchronization: TanStack Query with automatic cache invalidation for instant updates
- Collaborative Tasks: Shared task lists with real-time updates across users
- Theme Support: Light/dark mode with system preference
- Offline Persistence: Zustand with AsyncStorage
- Modern UI: Animated components with React Native Reanimated
- Error Handling: Comprehensive error handling with connection failure recovery
- React Native with Expo
- TypeScript
- TanStack Query for real-time data fetching and cache management
- Zustand for state management with persistence
- React Hook Form with Zod validation
- React Native Reanimated for animations
- NestJS framework
- PostgreSQL database
- Prisma ORM
- JWT authentication
- Swagger API documentation
- Node.js (v18 or higher)
- Bun (recommended) or npm/yarn
- Docker and Docker Compose
- Expo CLI (
npm install -g @expo/cli) - iOS Simulator (for iOS development) or Android Studio (for Android development)
git clone <repository-url>
cd passiNavigate to the backend directory:
cd backendInstall dependencies:
bun install
# or
npm installCreate environment file:
cp .env.example .env.localConfigure your .env.local:
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/passi?schema=public
JWT_SECRET=your-super-secret-jwt-key
PORT=4001Start the database:
bun run db:start
# or
npm run db:startRun database migrations:
bun run prisma:generate
bun run prisma:migrateStart the development server:
bun run dev
# or
npm run devThe backend will be available at http://localhost:4001
API documentation: http://localhost:4001/api
Navigate to the frontend directory:
cd frontendInstall dependencies:
bun install
# or
npm installCreate environment file:
cp .env.example .envConfigure your .env:
EXPO_PUBLIC_API_URL=http://localhost:4001- Start Backend (in
backend/directory):
bun run dev- Start Frontend (in
frontend/directory):
bun start- Run on Device/Simulator:
- Scan QR code with Expo Go app
- Press
ifor iOS simulator - Press
afor Android emulator - Press
wfor web browser
Since this app uses native modules, you need to create a local development build:
- Install Dependencies (in
frontend/directory):
bun install- Create Local Development Build:
For iOS:
bun run iosFor Android:
bun run android- Start Development Server:
bun startThe app will automatically open in the iOS Simulator or Android Emulator. If you don't have them installed:
iOS Simulator (macOS only):
- Install Xcode from App Store
- Open iOS Simulator:
open -a Simulator
Android Emulator:
- Install Android Studio
- Create and start an Android Virtual Device (AVD)
For quick testing without native modules:
bun start
# Then scan QR code with Expo Go appNote: Some features may not work in Expo Go due to native module dependencies.
Backend:
cd backend
bun run build
bun run start:prodFrontend:
cd frontend
bun run buildbun run dev- Start development server with databasebun run start:dev- Start development server onlybun run build- Build for productionbun run start:prod- Start production serverbun run db:start- Start PostgreSQL databasebun run db:stop- Stop PostgreSQL databasebun run prisma:generate- Generate Prisma clientbun run prisma:migrate- Run database migrationsbun run prisma:studio- Open Prisma Studio
bun start- Start Expo development serverbun run ios- Run on iOS Simulatorbun run android- Run on Android Emulatorbun run web- Run on web browser
POST /auth/login- User loginPOST /auth/register- User registration
GET /tasks- Get all tasks for current userPOST /tasks- Create new taskGET /tasks/:id- Get specific taskPATCH /tasks/:id- Update taskDELETE /tasks/:id- Delete task
GET /findAll- Get all usersGET /findOne/:id- Get specific userPUT /update/:id- Update user
id(UUID, Primary Key)name(String)email(String, Unique)password(String, Hashed)createdAt(DateTime)updatedAt(DateTime)
id(UUID, Primary Key)title(String)description(String, Optional)completed(Boolean, Default: false)userId(UUID, Foreign Key)createdAt(DateTime)updatedAt(DateTime)
The app uses TanStack Query for real-time synchronization through:
- Automatic Cache Invalidation: When tasks are created, updated, or deleted, the cache is automatically invalidated
- Background Refetching: Queries automatically refetch when the app regains focus
- Optimistic Updates: UI updates immediately while API calls are in progress
- Error Recovery: Failed requests are automatically retried
// When a task is created
const { mutateAsync: createTask } = useCreateTaskMutation();
// On success, TanStack Query automatically:
// 1. Invalidates the tasks cache
// 2. Refetches the tasks list
// 3. Updates all components displaying tasks- User-specific Tasks: Each user sees only their own tasks
- Real-time Updates: Changes are reflected immediately across all connected clients
- Offline Support: Tasks are cached locally and sync when connection is restored
The app uses JWT tokens for authentication. Tokens are automatically:
- Stored in AsyncStorage on login
- Attached to API requests
- Cleared on logout or token expiration
- Refreshed automatically when needed
The app supports:
- Light Mode: Clean, bright interface
- Dark Mode: Easy on the eyes
- System Mode: Follows device preference
frontend/
βββ src/
β βββ app/ # Expo Router screens
β β βββ auth/ # Authentication screens
β β βββ (app)/ # Main app screens
β βββ components/ # Reusable components
β βββ hooks/ # Custom React hooks
β βββ lib/ # Utilities and API client
β βββ services/ # API service functions
β βββ stores/ # Zustand stores
- Real-time Sync: Automatic cache invalidation provides instant updates
- Offline Support: Built-in caching with background sync
- Error Handling: Automatic retry logic and error recovery
- Performance: Optimistic updates and background refetching
- Developer Experience: Simple API with powerful features
- Zustand for Auth: Lightweight, persistent auth state
- TanStack Query for Data: Server state management with caching
- React Hook Form: Form state management with validation
- Cache Invalidation: Immediate UI updates through cache invalidation
- Background Refetching: Automatic data refresh when app regains focus
- Optimistic Updates: UI responds immediately to user actions
- Error Recovery: Automatic retry with exponential backoff
The app handles various error scenarios:
-
Network Errors:
- Automatic retry with exponential backoff
- Offline mode with cached data
- User-friendly error messages
-
Authentication Errors:
- Automatic token refresh
- Redirect to login on token expiration
- Clear local data on auth failure
-
API Errors:
- Graceful degradation
- Retry mechanisms
- Error boundaries for component-level recovery
// API client with error handling
export async function apiFetch<TResponse>(path: string, options = {}) {
try {
const response = await fetch(url, options);
if (!response.ok) {
// Handle 401 errors (token expired)
if (response.status === 401) {
clearUser();
throw new Error("Session expired");
}
throw new Error(payload?.error?.message || "Request failed");
}
return payload.data;
} catch (error) {
// Log error for debugging
console.error("API Error:", error);
throw error;
}
}-
Database Connection Error:
- Ensure Docker is running
- Run
bun run db:startin backend directory - Check DATABASE_URL in
.env.local
-
Frontend Can't Connect to Backend:
- Verify backend is running on port 4001
- Check
EXPO_PUBLIC_API_URLin frontend.env - Ensure no firewall blocking localhost
-
Development Build Issues:
- Clear cache:
bun start --clear - Reset Metro:
bun start --reset-cache - For iOS: Ensure Xcode is installed and iOS Simulator is available
- For Android: Ensure Android Studio is installed and AVD is created
- Clear cache:
-
Prisma Issues:
- Regenerate client:
bun run prisma:generate - Reset database:
bun run prisma:migrate:reset
- Regenerate client:
-
Real-time Sync Not Working:
- Check network connectivity
- Verify API endpoints are responding
- Clear TanStack Query cache if needed
-
iOS Build Fails:
- Install Xcode from App Store
- Open iOS Simulator:
open -a Simulator - Run
bun run iosagain
-
Android Build Fails:
- Install Android Studio
- Create Android Virtual Device (AVD)
- Run
bun run androidagain
-
App Won't Connect to Development Server:
- Ensure backend is running on port 4001
- Check device/simulator network settings
- Verify backend is accessible from device
This project is licensed under the MIT License.
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests if applicable
- Submit a pull request
For support, please open an issue in the repository or contact the development team.