mitlist/docs/chore-system.md

Chore System Documentation

1. Overview

The chore system is designed to help users manage tasks, both personal and within groups. It supports recurring chores, assignments, and a detailed history of all changes. This document provides a comprehensive overview of the system's architecture, data models, API endpoints, and frontend implementation.

2. Data Models

The chore system is built around three core data models: Chore, ChoreAssignment, and ChoreHistory.

2.1. Chore Model

The Chore model represents a task to be completed. It can be a personal chore or a group chore.

• id: The unique identifier for the chore.
• name: The name of the chore.
• description: A detailed description of the chore.
• type: The type of chore, either personal or group.
• group_id: The ID of the group the chore belongs to (if it's a group chore).
• created_by_id: The ID of the user who created the chore.
• frequency: The frequency of the chore, such as daily, weekly, or monthly.
• custom_interval_days: The number of days between occurrences for custom frequency chores.
• next_due_date: The next due date for the chore.
• last_completed_at: The timestamp of when the chore was last completed.

2.2. ChoreAssignment Model

The ChoreAssignment model represents the assignment of a chore to a user.

• id: The unique identifier for the assignment.
• chore_id: The ID of the chore being assigned.
• assigned_to_user_id: The ID of the user the chore is assigned to.
• due_date: The due date for the assignment.
• is_complete: A boolean indicating whether the assignment is complete.
• completed_at: The timestamp of when the assignment was completed.

2.3. ChoreHistory Model

The ChoreHistory model tracks all changes to a chore, such as creation, updates, and completion.

• id: The unique identifier for the history entry.
• chore_id: The ID of the chore the history entry belongs to.
• event_type: The type of event, such as created, updated, or completed.
• event_data: A JSON object containing details about the event.
• changed_by_user_id: The ID of the user who made the change.

3. API Endpoints

The chore system exposes a set of API endpoints for managing chores, assignments, and history.

3.1. Chores

• GET /api/v1/chores/all: Retrieves all chores for the current user.
• POST /api/v1/chores/personal: Creates a new personal chore.
• GET /api/v1/chores/personal: Retrieves all personal chores for the current user.
• PUT /api/v1/chores/personal/{chore_id}: Updates a personal chore.
• DELETE /api/v1/chores/personal/{chore_id}: Deletes a personal chore.
• POST /api/v1/chores/groups/{group_id}/chores: Creates a new group chore.
• GET /api/v1/chores/groups/{group_id}/chores: Retrieves all chores for a specific group.
• PUT /api/v1/chores/groups/{group_id}/chores/{chore_id}: Updates a group chore.
• DELETE /api/v1/chores/groups/{group_id}/chores/{chore_id}: Deletes a group chore.

3.2. Assignments

• POST /api/v1/chores/assignments: Creates a new chore assignment.
• GET /api/v1/chores/assignments/my: Retrieves all chore assignments for the current user.
• GET /api/v1/chores/chores/{chore_id}/assignments: Retrieves all assignments for a specific chore.
• PUT /api/v1/chores/assignments/{assignment_id}: Updates a chore assignment.
• DELETE /api/v1/chores/assignments/{assignment_id}: Deletes a chore assignment.
• PATCH /api/v1/chores/assignments/{assignment_id}/complete: Marks a chore assignment as complete.

3.3. History

• GET /api/v1/chores/{chore_id}/history: Retrieves the history for a specific chore.
• GET /api/v1/chores/assignments/{assignment_id}/history: Retrieves the history for a specific chore assignment.

4. Frontend Implementation

The frontend for the chore system is built using Vue.js and the Composition API. The main component is ChoresPage.vue, which is responsible for displaying the list of chores, handling user interactions, and communicating with the backend.

4.1. State Management

The ChoresPage.vue component uses Pinia for state management. The useChoreStore manages the state of the chores, including the list of chores, the current chore being edited, and the loading state.

4.2. User Experience

The user experience is designed to be intuitive and efficient. Users can easily view their chores, mark them as complete, and create new chores. The UI also provides feedback to the user, such as loading indicators and success messages.

5. Reliability and UX Recommendations

To improve the reliability and user experience of the chore system, the following recommendations are suggested:

5.1. Optimistic UI Updates

When a user marks a chore as complete, the UI should immediately reflect the change, even before the API call has completed. This will make the UI feel more responsive and reduce perceived latency.

5.2. More Robust Error Handling

The frontend should provide more specific and helpful error messages to the user. For example, if an API call fails, the UI should display a message that explains what went wrong and what the user can do to fix it.

5.3. Intuitive User Interface

The user interface could be improved to make it more intuitive and easier to use. For example, the chore creation form could be simplified, and the chore list could be made more scannable.

5.4. Improved Caching

The frontend should implement a more sophisticated caching strategy to reduce the number of API calls and improve performance. For example, the list of chores could be cached in local storage, and the cache could be invalidated when a new chore is created or an existing chore is updated.