Tasks

Tasks are the core data model in Softly. They support one-time and recurring schedules, category tagging, household assignment, reminders, and archive/restore.

Creating Tasks

Tasks can be created three ways:

1. Manual -- tap "Add Task", fill in title, date, category, recurrence
2. AI parse -- type or speak natural language (e.g. "renew passport in 3 months"), and Claude Haiku extracts structured fields
3. Templates -- apply a pre-built life template (e.g. "New Baby Checklist") that creates multiple tasks at once

Free users are limited to 10 tasks. Pro and Family tiers have unlimited tasks.

Recurring Tasks

Tasks can repeat on a day or month interval:

• repeat_interval_days -- repeat every N days (e.g. 14 for biweekly)
• repeat_interval_months -- repeat every N months (e.g. 6 for semiannual)
• weekdays_only -- skip weekends when calculating the next due date

When a recurring task is completed, it is not marked as done. Instead, the due date advances to the next occurrence and the completion_count increments. The task stays in the active list.

Overdue Detection

Overdue status is calculated relative to the user's local date (sent as user_date from the mobile client). A task is overdue if its due_date is before the user's current date and it is not completed.

The task list endpoint returns overdue, this-week, and total counts in the meta object so the mobile app can display filter badges without extra requests.

Completion Flow

Completing a task triggers several things:

1. A TaskCompletion record is created (used for streaks and stats)
2. Points are awarded (1 for regular, 1.5 for recurring)
3. If the user leveled up, level_up: true is returned in the response
4. If the task was recurring and overdue, a reschedule suggestion may be returned (based on the user's actual completion pattern vs configured interval)

The mobile app shows confetti on completion and a level-up toast when applicable.

Swipe Actions

The task list uses swipeable rows:

• Swipe right -- complete the task (green)
• Swipe left -- delete the task (red)

Batch completion with undo is available: if multiple tasks are completed quickly, a toast appears with an undo option.

Filters

The task list supports several filters via query parameters:

Filter	Parameter	Values
Status	status	overdue, this_week, upcoming, completed, all
Category	category_id	Category UUID
Search	q	Free text (matches title and description)
Shared only	shared_only	true
Archived	include_archived	true

Default behavior (no status filter) returns incomplete tasks only.

Archive

Tasks can be archived instead of deleted. Archived tasks are hidden from the default list but can be restored. This is useful for seasonal tasks that will come back.

Smart Rescheduling

When a recurring task is completed while overdue, the backend checks the user's last 5 completion intervals. If the average actual interval differs from the configured interval by more than 20%, it returns a reschedule suggestion. The mobile app shows a modal asking if the user wants to adjust the frequency.

Monthly Stats

The calendar view uses the monthly_stats endpoint to show completion counts per month, allowing users to see their activity over time.