749 lines
25 KiB
Markdown
749 lines
25 KiB
Markdown
# Carry Your Live - Mobile To-Do & Calendar App
|
|
|
|
A minimalist, offline-first task management app built with Expo, React Native, and WatermelonDB. Features multiple screens with bottom navigation, social features, and a full-featured backend API.
|
|
|
|
## 📝 Recent Progress (v1.1.0 - Unreleased)
|
|
|
|
### Added
|
|
- **Friends feature**: Friend requests, accept/decline/remove, user search, full backend routes
|
|
- **Assignee field on tasks**: Schema v7, model, types, forms, sync, task actions
|
|
- **AssigneeSelector component** and assignee display in TaskItem
|
|
- **QuickAddBar** on tasks overview (copied from calendar)
|
|
- **Backend**: Mounted friends route, added assigneeId to task validation and sync
|
|
|
|
### Changed
|
|
- Due date prefilled from Calendar "+" button
|
|
- 12-hour time formatting across task rows and pickers
|
|
- Calendar strip scrolls to selected day when navigating months
|
|
- Calendar completion toggle now handles repeating tasks and reminders
|
|
- Task color strips now use the task's category color
|
|
|
|
### Fixed
|
|
- WheelTimePicker FlatList scroll clamping - all hours (0-23) and minutes (0-59) reachable
|
|
- WheelTimePicker selection highlight background connecting selected item with colon separator
|
|
- WheelTimePicker number alignment in scroll list
|
|
- Tasks without a due date no longer get overdue styling
|
|
- `useOverdueTasks` infinite re-subscription loop (Date.now in effect deps)
|
|
- Web/Android crashes from decorator transform ordering (babel config)
|
|
- FormButtons crash outside FormProvider; Cancel navigation fallback
|
|
- Task repeat settings, reminders and series info now sync to backend
|
|
|
|
### Removed
|
|
- Task color picker (task color now comes from its category)
|
|
- Drag lift popup from TaskItem (scale + shadow on drag)
|
|
- Checkbox from task items
|
|
- Selection bar overlapping QuickAddBar on tasks overview
|
|
|
|
---
|
|
|
|
## Features
|
|
|
|
### Core Functionality
|
|
- **Offline-First Architecture**: Full CRUD operations work offline with WatermelonDB + SQLite
|
|
- **Auto-Sync**: Background synchronization with custom Postgres API when online
|
|
- **Cross-Platform**: iOS, Android, and Web from single codebase
|
|
- **Desktop Support**: Electron wrapper for desktop app distribution
|
|
|
|
### Screens
|
|
|
|
#### 1. Tasks Screen (To-Do List)
|
|
- **Header**: App logo + "TODO" title with rounded corners
|
|
- **Category Filter**: Horizontal scrollable chips (Work, Personal, School, Shopping, Health, Finance, All)
|
|
- Single selection with visual feedback (thicker border, shadow, scale animation)
|
|
- Instant task filtering
|
|
- **QuickAddBar**: Quick task creation from list view
|
|
- **Task List**: Virtualized FlatList with sections (Pending/Completed)
|
|
- Task title (truncated with ellipsis)
|
|
- Three-dot overflow menu (Edit, Delete, Duplicate, Mark Complete, Change Category, Change Priority)
|
|
- Priority badges with colors
|
|
- Due date/time with overdue/due-today highlighting
|
|
- Category color indicator strip
|
|
- Assignee display
|
|
- Swipe actions (left: delete, right: complete)
|
|
- Drag-to-reorder with visual drop indicators
|
|
- Long press → Selection mode (multi-delete, multi-complete, change category/priority)
|
|
- **Floating Action Button**: Bottom-right, opens Add Task screen
|
|
|
|
#### 2. Calendar Screen
|
|
- **Date Strip**: Horizontal scrollable days of current month
|
|
- Current day highlighted, scrolls to selected day on month change
|
|
- **Month Label**: Centered (e.g., "JAN 2026")
|
|
- **QuickAddBar**: Quick task creation for selected date
|
|
- **Task List**: Tasks for selected day with category color, title, time, completion status
|
|
- **Analog Clock Widget**: Decorative analog clock display
|
|
- **Empty State**: "No tasks scheduled."
|
|
- **Day View**: Detailed view for selected day (pushes to stack)
|
|
|
|
#### 3. Stats Screen
|
|
- Client-side statistics (`useStats` hook)
|
|
- Task completion metrics
|
|
- Category and priority breakdowns
|
|
|
|
#### 4. Settings Screen
|
|
- **Account**: Login/Register/Sign Out (SyncModal)
|
|
- **Server URL Override**: Custom API endpoint configuration
|
|
- **Appearance**: Accent color picker (dark mode toggle planned)
|
|
- **Task Defaults**: Default category, sort order (Date, Priority, Alphabetically, Creation Date), show completed toggle
|
|
- **Calendar**: Days ahead to display
|
|
- **Reminders**: Global reminder preference (stored, wiring in progress)
|
|
- **Notifications**: Toggle (stored, wiring in progress)
|
|
- **Legal**: Privacy Policy, Terms of Service
|
|
- **About**: Version info
|
|
|
|
#### 5. Add New Task Screen
|
|
- **Category Selector**: Horizontal row of colored circles (required)
|
|
- **Task Name**: Single-line input, 100 char max (required)
|
|
- **Subtasks**: Unlimited, add/remove individually, nested subtask support
|
|
- **Date & Time**: Date picker, time picker (WheelTimePicker), calendar button
|
|
- **Priority**: Dropdown (None, Low, Medium, High, Critical) with color indicators
|
|
- **Repeat Profile**: Recurring task configuration
|
|
- **Reminder**: Reminder offset selector
|
|
- **Assignee**: Assign task to friend
|
|
- **Description**: Multi-line text area, 1000 char max
|
|
- **Bottom Actions**: Submit (primary) / Cancel (secondary) fixed buttons
|
|
|
|
#### 6. Task Detail Screen
|
|
- Full task view with all fields
|
|
- Subtask management (add, complete, reorder, convert to task)
|
|
- Edit functionality
|
|
- Repeat profile configuration
|
|
|
|
#### 7. Subtask Detail Screen
|
|
- Nested subtask management
|
|
- Convert subtask ↔ task
|
|
- Re-parent subtasks
|
|
|
|
#### 8. Sync Modal
|
|
- Login/Register forms
|
|
- Forgot/Reset password flow
|
|
- Server URL configuration
|
|
- Sync status display
|
|
|
|
### Task Features
|
|
- **Nested Subtasks**: Unlimited depth, re-parenting, drag reorder
|
|
- **Repeating Tasks**: Repeat profiles, series IDs, this/future/all delete scopes, undo-complete
|
|
- **Categories/Tags**: 6 default categories with colors, custom category editor
|
|
- **Priorities**: None, Low, Medium, High, Critical with color badges
|
|
- **Due Dates/Times**: With all-day option
|
|
- **Reminders**: Per-task reminder offsets
|
|
- **Assignees**: Assign tasks to friends
|
|
- **Overdue/Due Today**: Visual highlighting
|
|
|
|
### Social Features
|
|
- **Friends System**: Send/accept/decline/remove friend requests
|
|
- **User Search**: Find users by username/email
|
|
- **Task Assignment**: Assign tasks to friends (client-side, backend schema ready)
|
|
|
|
---
|
|
|
|
## Tech Stack
|
|
|
|
| Layer | Technology |
|
|
|-------|------------|
|
|
| Framework | Expo (React Native) / Expo Router v3 |
|
|
| Language | TypeScript (strict mode) |
|
|
| Navigation | Expo Router (file-based) |
|
|
| Database | WatermelonDB + SQLite (expo-sqlite) |
|
|
| State | WatermelonDB reactive queries (no Redux) |
|
|
| Forms | React Hook Form + Zod validation |
|
|
| UI Components | React Native Paper + Custom components |
|
|
| Animations | React Native Reanimated v3 |
|
|
| Date/Time | @react-native-community/datetimepicker + date-fns + WheelTimePicker |
|
|
| Build | EAS Build / Gradle (local APK) / Electron Builder (desktop) |
|
|
| CI/CD | Gitea Actions (`.gitea/workflows/build-apk.yml`) |
|
|
| Backend | Node.js + Express + TypeScript |
|
|
| Backend DB | PostgreSQL + Drizzle ORM |
|
|
| Auth | JWT (access + refresh tokens) |
|
|
| Validation | Zod (shared with frontend) |
|
|
|
|
---
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
carry-your-live/
|
|
├── app/
|
|
│ ├── _layout.tsx # Root layout + DatabaseProvider + AuthProvider
|
|
│ ├── (tabs)/
|
|
│ │ ├── _layout.tsx # Bottom tab navigator
|
|
│ │ ├── index.tsx # Tasks screen
|
|
│ │ ├── calendar.tsx # Calendar screen
|
|
│ │ ├── stats.tsx # Stats screen
|
|
│ │ └── settings.tsx # Settings screen
|
|
│ ├── add-task.tsx # Add Task screen
|
|
│ ├── day-view.tsx # Calendar day detail
|
|
│ ├── task-detail.tsx # Task view/edit
|
|
│ └── subtask-detail.tsx # Subtask view/edit
|
|
├── src/
|
|
│ ├── components/ # Reusable UI components (30+)
|
|
│ │ ├── Header.tsx
|
|
│ │ ├── CategoryFilter.tsx
|
|
│ │ ├── TaskList.tsx
|
|
│ │ ├── TaskItem.tsx
|
|
│ │ ├── FloatingActionButton.tsx
|
|
│ │ ├── CategorySelector.tsx
|
|
│ │ ├── TaskNameInput.tsx
|
|
│ │ ├── SubtasksSection.tsx
|
|
│ │ ├── DateTimePicker.tsx
|
|
│ │ ├── PrioritySelector.tsx
|
|
│ │ ├── DescriptionInput.tsx
|
|
│ │ ├── FormButtons.tsx
|
|
│ │ ├── ListItem.tsx
|
|
│ │ ├── AnalogClock.tsx
|
|
│ │ ├── AssigneeSelector.tsx
|
|
│ │ ├── CategoryEditorModal.tsx
|
|
│ │ ├── ColorPickerInput.tsx
|
|
│ │ ├── ColorWheel.tsx
|
|
│ │ ├── DateTimeInput.tsx
|
|
│ │ ├── ForgotPasswordModal.tsx
|
|
│ │ ├── FriendsModal.tsx
|
|
│ │ ├── LegalModal.tsx
|
|
│ │ ├── OptionPickerModal.tsx
|
|
│ │ ├── QuickAddBar.tsx
|
|
│ │ ├── ReminderSelector.tsx
|
|
│ │ ├── RepeatSelector.tsx
|
|
│ │ ├── ServerUrlModal.tsx
|
|
│ │ ├── SubtaskItem.tsx
|
|
│ │ ├── SyncModal.tsx
|
|
│ │ ├── SyncStatus.tsx
|
|
│ │ ├── TabBarIcon.tsx
|
|
│ │ ├── TaskDeleteModal.tsx
|
|
│ │ ├── TaskOverflowMenu.tsx
|
|
│ │ ├── UpdateNotifier.tsx
|
|
│ │ └── WheelTimePicker.tsx
|
|
│ ├── constants/
|
|
│ │ └── index.ts # Categories, priorities, colors, reminder options
|
|
│ ├── database/
|
|
│ │ ├── schema.ts # WatermelonDB schema (v21)
|
|
│ │ ├── index.ts # Database instance + collections
|
|
│ │ ├── sync.ts # Custom API sync adapter (25KB)
|
|
│ │ ├── migrations.ts # Schema migrations
|
|
│ │ ├── adapter.ts # Platform-specific adapters
|
|
│ │ └── tombstones.ts # Deleted record tracking
|
|
│ ├── hooks/
|
|
│ │ ├── useDatabase.tsx # Database context & providers
|
|
│ │ ├── useTasks.tsx # Task queries with reactive state
|
|
│ │ ├── useCategories.tsx # Category queries
|
|
│ │ ├── useTasksByDate.tsx # Calendar date queries
|
|
│ │ ├── useFriends.tsx # Friends state & actions
|
|
│ │ ├── useAuth.tsx # Authentication state
|
|
│ │ └── useStats.tsx # Statistics computation
|
|
│ ├── models/
|
|
│ │ ├── Task.ts # Task model (assigneeId, repeat, reminders)
|
|
│ │ ├── Category.ts
|
|
│ │ ├── Subtask.ts
|
|
│ │ ├── RepeatProfile.ts
|
|
│ │ ├── Friendship.ts
|
|
│ │ └── Tombstone.ts
|
|
│ ├── services/
|
|
│ │ ├── api.ts # API client with auth
|
|
│ │ ├── auth.ts # Auth token management
|
|
│ │ ├── friends.ts # Friends API calls
|
|
│ │ ├── notifications.ts # Reminder scheduling (expo-notifications)
|
|
│ │ ├── repeat.ts # Repeat task generation
|
|
│ │ └── taskActions.ts # Task CRUD + sync operations
|
|
│ ├── theme/
|
|
│ │ ├── index.ts # Theme context, colors, spacing
|
|
│ │ └── theme.tsx # Accent color picker, settings sync
|
|
│ ├── types/
|
|
│ │ └── index.ts # TypeScript interfaces
|
|
│ └── utils/
|
|
│ ├── date.ts # Date formatting utilities
|
|
│ ├── format.ts # General formatting
|
|
│ └── validation.ts # Zod schemas
|
|
├── backend/ # Backend API (separate package)
|
|
│ ├── src/
|
|
│ │ ├── index.ts # Express app entry
|
|
│ │ ├── db/
|
|
│ │ │ ├── schema.ts # Drizzle schema (Postgres)
|
|
│ │ │ └── index.ts # DB connection
|
|
│ │ ├── routes/
|
|
│ │ │ ├── auth.ts # Register, login, me, forgot/reset password
|
|
│ │ │ ├── categories.ts # Category CRUD
|
|
│ │ │ ├── tasks.ts # Task CRUD + batch
|
|
│ │ │ ├── subtasks.ts # Subtask CRUD
|
|
│ │ │ ├── sync.ts # Pull/push sync endpoints
|
|
│ │ │ ├── users.ts # User profile & settings
|
|
│ │ │ ├── friends.ts # Friend requests, search, management
|
|
│ │ │ ├── repeatProfiles.ts# Repeat profile CRUD
|
|
│ │ │ └── pushNotifications.ts
|
|
│ │ ├── middleware/
|
|
│ │ │ ├── auth.ts # JWT verification
|
|
│ │ │ ├── errorHandler.ts
|
|
│ │ │ └── validation.ts # Zod validation middleware
|
|
│ │ ├── services/
|
|
│ │ └── utils/
|
|
│ ├── drizzle.config.ts
|
|
│ └── Dockerfile
|
|
├── electron/ # Desktop app entry
|
|
├── android/ # Native Android project
|
|
├── assets/ # Images, fonts
|
|
├── patches/ # patch-package fixes
|
|
└── plugins/ # Expo config plugins
|
|
```
|
|
|
|
---
|
|
|
|
## Data Models
|
|
|
|
### Task
|
|
```typescript
|
|
{
|
|
id: string;
|
|
title: string;
|
|
description: string;
|
|
categoryId: string;
|
|
priority: 'none' | 'low' | 'medium' | 'high' | 'critical';
|
|
completed: boolean;
|
|
dueDate: number; // timestamp (ms)
|
|
dueTime: string; // "HH:MM" (24h stored, 12h displayed)
|
|
allDay: boolean;
|
|
assigneeId: string | null;
|
|
repeatProfileId: string | null;
|
|
seriesId: string | null; // For repeating tasks
|
|
isTemplate: boolean; // Series template
|
|
reminderOffset: string | null; // e.g., "5m", "1h", "1d"
|
|
createdAt: Date;
|
|
updatedAt: Date;
|
|
subtasks: Subtask[];
|
|
}
|
|
```
|
|
|
|
### Category
|
|
```typescript
|
|
{
|
|
id: string;
|
|
name: string;
|
|
color: '#HEX';
|
|
order: number;
|
|
createdAt: Date;
|
|
updatedAt: Date;
|
|
}
|
|
```
|
|
|
|
### Subtask
|
|
```typescript
|
|
{
|
|
id: string;
|
|
taskId: string;
|
|
parentSubtaskId: string | null; // For nesting
|
|
title: string;
|
|
completed: boolean;
|
|
order: number;
|
|
assigneeId: string | null;
|
|
createdAt: Date;
|
|
updatedAt: Date;
|
|
}
|
|
```
|
|
|
|
### Repeat Profile
|
|
```typescript
|
|
{
|
|
id: string;
|
|
name: string;
|
|
frequency: 'daily' | 'weekly' | 'monthly' | 'yearly' | 'custom';
|
|
interval: number;
|
|
daysOfWeek: number[]; // 0-6 for weekly
|
|
dayOfMonth: number | null; // For monthly
|
|
monthOfYear: number | null; // For yearly
|
|
endDate: number | null; // Timestamp
|
|
occurrences: number | null;
|
|
createdAt: Date;
|
|
updatedAt: Date;
|
|
}
|
|
```
|
|
|
|
### Friendship
|
|
```typescript
|
|
{
|
|
id: string;
|
|
userId: string; // Requester
|
|
friendId: string; // Recipient
|
|
status: 'pending' | 'accepted' | 'declined' | 'blocked';
|
|
createdAt: Date;
|
|
updatedAt: Date;
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Default Categories
|
|
| Name | Color | Order |
|
|
|------|-------|-------|
|
|
| Work | #E53935 (Red) | 0 |
|
|
| Personal | #43A047 (Green) | 1 |
|
|
| School | #1E88E5 (Blue) | 2 |
|
|
| Shopping | #FB8C00 (Orange) | 3 |
|
|
| Health | #8E24AA (Purple) | 4 |
|
|
| Finance | #FDD835 (Yellow) | 5 |
|
|
|
|
---
|
|
|
|
## Priority Colors
|
|
| Priority | Color |
|
|
|----------|-------|
|
|
| None | #9E9E9E |
|
|
| Low | #43A047 |
|
|
| Medium | #FB8C00 |
|
|
| High | #E53935 |
|
|
| Critical | #B71C1C |
|
|
|
|
---
|
|
|
|
## Getting Started
|
|
|
|
### Prerequisites
|
|
- Node.js 20+
|
|
- npm or yarn
|
|
- Expo CLI (`npm install -g expo-cli`)
|
|
- iOS Simulator (Mac) / Android Studio for mobile testing
|
|
- PostgreSQL 16+ (or Docker)
|
|
|
|
### Installation
|
|
```bash
|
|
cd carry-your-live
|
|
npm install
|
|
|
|
cd ../backend
|
|
npm install
|
|
```
|
|
|
|
### Development
|
|
|
|
#### Frontend
|
|
```bash
|
|
cd carry-your-live
|
|
|
|
# Start Expo dev server
|
|
npx expo start
|
|
|
|
# Run on specific platform
|
|
npx expo start --ios
|
|
npx expo start --android
|
|
npx expo start --web
|
|
```
|
|
|
|
#### Backend
|
|
```bash
|
|
cd backend
|
|
|
|
# Start PostgreSQL (Docker)
|
|
docker-compose up -d postgres
|
|
|
|
# Configure environment
|
|
cp .env.example .env
|
|
# Edit .env with your settings
|
|
|
|
# Run migrations
|
|
npm run db:push
|
|
|
|
# Start dev server
|
|
npm run dev
|
|
```
|
|
|
|
Server runs at `http://localhost:3000` (health check: `GET /health`)
|
|
|
|
#### Desktop (Electron)
|
|
```bash
|
|
cd carry-your-live
|
|
|
|
# Development with live reload
|
|
npm run desktop:dev
|
|
|
|
# Production build
|
|
npm run desktop:dist
|
|
```
|
|
|
|
### Building
|
|
|
|
#### EAS Build (cloud)
|
|
```bash
|
|
# Install EAS CLI
|
|
npm install -g eas-cli
|
|
|
|
# Configure project
|
|
eas build:configure
|
|
|
|
# Build for platforms
|
|
eas build --platform ios
|
|
eas build --platform android
|
|
eas build --platform web
|
|
```
|
|
Profiles defined in `eas.json` (`development`, `preview`, `production`; production auto-increments version code).
|
|
|
|
#### Gradle (local Android APK)
|
|
```bash
|
|
cd carry-your-live/android
|
|
|
|
# Debug APK (unsigned)
|
|
./gradlew assembleDebug
|
|
|
|
# Release APK (signed with debug keystore)
|
|
./gradlew assembleRelease
|
|
```
|
|
Output:
|
|
```
|
|
android/app/build/outputs/apk/debug/app-debug.apk
|
|
android/app/build/outputs/apk/release/app-release.apk
|
|
```
|
|
|
|
---
|
|
|
|
## CI/CD Pipeline (Gitea Actions)
|
|
|
|
`.gitea/workflows/build-apk.yml` builds a release APK on every push to `main` (also manually triggerable via `workflow_dispatch`):
|
|
|
|
1. **Checkout** and setup Node 22, JDK 17 (Temurin)
|
|
2. **Android SDK**: installs cmdline-tools, licenses, platform-tools, `platforms;android-35`, `build-tools;35.0.0`, `ndk;27.1.12297006`
|
|
3. **JS deps**: `npm ci` in `carry-your-live/`
|
|
4. **Debug keystore**: generates `carry-your-live/android/app/debug.keystore` with `keytool`
|
|
5. **Build**: `./gradlew assembleRelease` in `carry-your-live/android/`
|
|
6. **Upload**: APK saved as `carry-your-live-release` artifact
|
|
|
|
To run locally exactly as CI does:
|
|
```bash
|
|
keytool -genkeypair -v \
|
|
-keystore carry-your-live/android/app/debug.keystore \
|
|
-alias androiddebugkey -storepass android -keypass android \
|
|
-keyalg RSA -keysize 2048 -validity 10000 \
|
|
-dname "CN=Android Debug,O=Android,C=US"
|
|
cd carry-your-live/android && ./gradlew assembleRelease
|
|
```
|
|
|
|
---
|
|
|
|
## Backend API Specification
|
|
|
|
Server runs at `http://localhost:3000/api` (configurable in `src/services/api.ts` and `src/database/sync.ts`):
|
|
|
|
### Authentication
|
|
- `POST /api/auth/register` - Register new user
|
|
- `POST /api/auth/login` - Login (returns access + refresh tokens)
|
|
- `POST /api/auth/refresh` - Refresh access token
|
|
- `POST /api/auth/forgot-password` - Request password reset
|
|
- `POST /api/auth/reset-password` - Reset password with token
|
|
- `GET /api/auth/me` - Get current user
|
|
|
|
### Categories
|
|
- `GET /api/categories` - List categories
|
|
- `POST /api/categories` - Create category
|
|
- `PATCH /api/categories/:id` - Update category
|
|
- `DELETE /api/categories/:id` - Delete category
|
|
|
|
### Tasks
|
|
- `GET /api/tasks` - List tasks (with filters: category, completed, due date range, assignee)
|
|
- `GET /api/tasks/:id` - Get task with subtasks
|
|
- `POST /api/tasks` - Create task
|
|
- `PATCH /api/tasks/:id` - Update task
|
|
- `DELETE /api/tasks/:id` - Delete task (scopes: this/future/all for repeating)
|
|
- `POST /api/tasks/batch` - Batch operations
|
|
|
|
### Subtasks
|
|
- `GET /api/subtasks/task/:taskId` - List subtasks for task
|
|
- `POST /api/subtasks/task/:taskId` - Create subtask
|
|
- `PATCH /api/subtasks/:id` - Update subtask
|
|
- `DELETE /api/subtasks/:id` - Delete subtask
|
|
|
|
### Repeat Profiles
|
|
- `GET /api/repeat-profiles` - List repeat profiles
|
|
- `POST /api/repeat-profiles` - Create repeat profile
|
|
- `PATCH /api/repeat-profiles/:id` - Update repeat profile
|
|
- `DELETE /api/repeat-profiles/:id` - Delete repeat profile
|
|
|
|
### Users
|
|
- `GET /api/users/me` - Get user with settings
|
|
- `PATCH /api/users/me/settings` - Update settings (darkMode, defaultCategoryId, sortOrder, etc.)
|
|
- `GET /api/users/search` - Search users (for friends)
|
|
|
|
### Friends
|
|
- `GET /api/friends` - List accepted friends
|
|
- `GET /api/friends/requests` - List pending requests (incoming/outgoing)
|
|
- `POST /api/friends/request` - Send friend request
|
|
- `PATCH /api/friends/request/:id/accept` - Accept request
|
|
- `PATCH /api/friends/request/:id/decline` - Decline request
|
|
- `DELETE /api/friends/:id` - Remove friend
|
|
|
|
### Sync (Offline-first)
|
|
- `GET /api/sync?since=<timestamp>` - Pull changes since timestamp
|
|
- `POST /api/sync/push` - Push local changes
|
|
|
|
---
|
|
|
|
## Sync Protocol
|
|
|
|
The sync endpoint uses a cursor-based approach with tombstones:
|
|
|
|
1. **Pull**: Client sends `since` timestamp, server returns all changes since then
|
|
```json
|
|
{
|
|
"categories": [...],
|
|
"tasks": [...],
|
|
"subtasks": [...],
|
|
"repeatProfiles": [...],
|
|
"friendships": [...],
|
|
"tombstones": [...],
|
|
"timestamp": 1234567890
|
|
}
|
|
```
|
|
|
|
2. **Push**: Client sends batched changes with `lastPulledAt`
|
|
```json
|
|
{
|
|
"changes": {
|
|
"categories": [...],
|
|
"tasks": [...],
|
|
"subtasks": [...],
|
|
"repeatProfiles": [...],
|
|
"friendships": [...]
|
|
},
|
|
"tombstones": [...],
|
|
"lastPulledAt": 1234567890
|
|
}
|
|
```
|
|
|
|
3. **Conflict Resolution**: Last-write-wins based on `updatedAt` (customizable in `src/database/sync.ts`)
|
|
|
|
---
|
|
|
|
## Configuration
|
|
|
|
### Frontend Environment Variables
|
|
Create `.env` file in `carry-your-live/`:
|
|
```
|
|
EXPO_PUBLIC_API_URL=http://your-api-url/api
|
|
```
|
|
|
|
### Backend Environment Variables
|
|
Create `.env` file in `backend/`:
|
|
```
|
|
DATABASE_URL=postgresql://user:pass@localhost:5432/carry_your_live
|
|
JWT_SECRET=your-32-char-secret
|
|
PORT=3000
|
|
NODE_ENV=development
|
|
FRONTEND_URL=http://localhost:8081
|
|
```
|
|
|
|
### App Config
|
|
Modify `app.json` for:
|
|
- App name, slug, version
|
|
- Icon, splash screen
|
|
- Permissions (notifications, etc.)
|
|
- Orientation, theme
|
|
|
|
---
|
|
|
|
## Visual Style Guide
|
|
|
|
- **Background**: White (#FFFFFF) / Dark mode (planned)
|
|
- **Primary Accent**: #E53935 (Pink/Red) - customizable
|
|
- **Typography**: Black (#212121) primary, #757575 secondary, #9E9E9E tertiary
|
|
- **Borders**: Thin (#E0E0E0), selected #E53935
|
|
- **Radius**: 16-20px for cards/buttons/inputs
|
|
- **Spacing**: 8px grid system
|
|
- **Shadows**: Minimal (elevation 1-3)
|
|
- **Animations**: 150-250ms, cubic easing
|
|
|
|
---
|
|
|
|
## Offline-First Architecture
|
|
|
|
```
|
|
┌─────────────┐ ┌──────────────┐ ┌─────────────┐
|
|
│ Expo App │────▶│ WatermelonDB │────▶│ Backend │
|
|
│ (iOS/Android│ │ (SQLite) │ │ (Postgres) │
|
|
│ Web) │◀───▶│ + Sync │◀───▶│ │
|
|
└─────────────┘ └──────────────┘ └─────────────┘
|
|
```
|
|
|
|
1. All writes go to local SQLite first
|
|
2. Reactive queries update UI instantly
|
|
3. Background sync pushes/pulls changes
|
|
4. Conflict resolution: last-write-wins (customizable)
|
|
5. Tombstones track deletions for sync
|
|
|
|
---
|
|
|
|
## Current Implementation Status
|
|
|
|
Based on code audit (August 2026):
|
|
|
|
| Feature | Status | Notes |
|
|
|---------|--------|-------|
|
|
| Core CRUD (tasks, subtasks, categories) | ✅ Complete | |
|
|
| Nested subtasks | ✅ Complete | Unlimited depth |
|
|
| Repeating tasks | ✅ Complete | Profiles, series, this/future/all delete |
|
|
| Categories & priorities | ✅ Complete | |
|
|
| Calendar with date strip | ✅ Complete | Month nav, day detail |
|
|
| Stats screen | ✅ Complete | Client-side only |
|
|
| Settings screen | ✅ Complete | Most settings wired |
|
|
| Friends system | ✅ Complete | Backend + UI |
|
|
| Task assignees | ✅ Complete | Schema v7, UI, sync |
|
|
| QuickAddBar | ✅ Complete | Tasks + Calendar |
|
|
| Offline sync (WatermelonDB) | ✅ Complete | Schema v21, tombstones |
|
|
| Backend API | ✅ Complete | Express + Drizzle + Postgres |
|
|
| Auth (JWT) | ✅ Complete | Register, login, refresh, forgot/reset |
|
|
| Dark mode / theme toggle | ❌ Missing | Backend column exists, UI not implemented |
|
|
| Notifications toggle | 🟡 Partial | Stored but not respected |
|
|
| Global reminder preference | 🟡 Partial | Stored but not applied |
|
|
| Forgot/reset password UI | 🟡 Partial | Backend done, no client UI |
|
|
| Pull-to-refresh → sync | 🟡 Partial | Reloads local only |
|
|
| Client settings sync | 🟡 Partial | AsyncStorage only, not synced to backend |
|
|
| Reminder enum mismatch | 🟡 Partial | Client uses '5m'/'1h', spec uses minutes |
|
|
|
|
---
|
|
|
|
## Roadmap Highlights
|
|
|
|
### v1.1.0 — Friends & Assignees (Current Unreleased)
|
|
- Ship existing Unreleased changes
|
|
- Fix notifications toggle, wire up `rescheduleAllReminders()`
|
|
- Apply global reminder preference
|
|
- Make pull-to-refresh trigger real sync
|
|
- Add forgot/reset password UI
|
|
- Unify reminder offset enums
|
|
|
|
### v1.2.0 — Theming & Findability
|
|
- Light mode + follow-system-theme
|
|
- Sync all settings to `PATCH /users/me/settings`
|
|
- Task search (filter + global)
|
|
- Friend request badges/indicators
|
|
|
|
### v1.3.0 — Stats & Insights
|
|
- Persisted stats snapshots
|
|
- Productivity trends, streaks
|
|
- Export stats (CSV/image)
|
|
|
|
### v1.4.0 — Quick Capture & Calendar UX
|
|
- Natural language quick-add
|
|
- Drag-and-drop rescheduling in calendar
|
|
- Month grid view
|
|
- "Today at a glance" dashboard
|
|
|
|
### v1.5.0 — Power Tools & Personalization
|
|
- Task templates, soft-archive, attachments
|
|
- Markdown support, deep links
|
|
- Biometric lock, haptics, reduced motion
|
|
- Android home-screen widget
|
|
|
|
### v2.0.0 — Collaboration
|
|
- Real task assignment delivery
|
|
- Shared lists with permissions
|
|
- Server push notifications (FCM/APNs)
|
|
- Comments/activity feed
|
|
|
|
---
|
|
|
|
## Contributing
|
|
|
|
1. Follow existing code conventions
|
|
2. Use TypeScript strict mode
|
|
3. Write components with React Hook Form + Zod
|
|
4. Use WatermelonDB decorators for models
|
|
5. Test offline scenarios
|
|
6. Run `npm run lint` and `npm run typecheck` before committing
|
|
|
|
---
|
|
|
|
## License
|
|
|
|
MIT |