oikos/DESIGN.md

Housekeeping Design

Goal

Housekeeping adds a simplified mobile/PWA module for the cleaner workflow in Oikos. It keeps the existing private-network, authenticated-session security model and exposes no public endpoints.

User Experience

The /housekeeping route is a focused module that follows the same toolbar, tab, card, and chip patterns used by the rest of Oikos:

• Dashboard: staff-specific check-in/check-out actions, visits this month, last visit, pending/finished chores, pending payments, and a compact monthly payment chart.
• Tasks: suggested chore templates, custom chore creation, urgency-sorted recurring tasks, and one-tap completion.
• Reports: camera upload plus text description for maintenance occurrences.
• Staff: one or more housekeeper people, contact data, profile pictures, daily rates, and payment schedules.

Accessibility constraints:

• Primary actions are at least 44px high.
• Check-in/out is a compact top-toolbar action, matching the small action pattern used elsewhere in the app.
• Status is communicated by text and color, not color alone.
• Inputs and buttons have explicit labels or accessible names.
• Icons use the locally bundled Lucide runtime; no external CDN is introduced.

Data Model

housekeeping_work_sessions

Stores point/finance records:

• id
• worker_id
• check_in
• check_out
• daily_rate
• extras
• calendar_event_id
• created_by
• created_at
• updated_at

Monthly amount is calculated as SUM(daily_rate + extras) for sessions whose check_in belongs to the requested month. Each check-in creates a linked local calendar event for the selected staff member. Check-out updates that event end time.

housekeeping_decay_tasks

Stores dynamic recurring cleaning tasks:

• id
• name
• area
• frequency_days
• last_completed
• created_by
• created_at
• updated_at

Urgency is computed at read time:

urgency = (now - last_completed) / frequency_days

Status mapping:

• overdue: due date is before today.
• today: due date is today.
• ok: due date is in the future.

Rows with no last_completed are treated as overdue.

housekeeping_supply_requests

Stores quick supply requests and links each request to an Oikos shopping item:

• id
• name
• quantity
• shopping_item_id
• created_by
• created_at

The supply request transaction always appends an item to the main shopping_items table. If no shopping list exists, the backend creates a private authenticated list named Housekeeping.

housekeeping_maintenance_log

Stores maintenance occurrences:

• id
• description
• photo_url
• created_by
• created_at
• updated_at

photo_url accepts self-contained data:image/png|jpeg|webp;base64,... values only, keeping uploaded camera photos inside the authenticated Oikos database boundary.

housekeeping_workers

Stores housekeeper-specific employment/payment settings while keeping the person unified with Oikos user/contact/birthday data:

• id
• user_id
• daily_rate
• payment_schedule
• calendar_color
• notes
• created_at
• updated_at

The linked users row is excluded from normal Family Management and Family APIs through the housekeeping_workers association, but remains synchronized with contacts and birthdays. Multiple housekeepers can be registered; each has its own linked users row. calendar_color controls the default color used for housekeeping visit events. Visit events use the cleaning icon (sparkles).

REST API

All endpoints are mounted under /api/v1/housekeeping and inherit the existing requireAuth and CSRF middleware.

• GET /summary?month=YYYY-MM
• GET /dashboard
• GET /task-templates
• GET /worker
• GET /workers
• POST /worker
• GET /work-sessions?month=YYYY-MM
• POST /work-sessions/check-in
• POST /work-sessions/check-out
• GET /decay-tasks
• POST /decay-tasks
• PATCH /decay-tasks/:taskId
• POST /decay-tasks/:taskId/complete
• DELETE /decay-tasks/:taskId
• POST /supply-requests
• GET /maintenance-log
• POST /maintenance-log