CleanShare - Household Chore Management App

A full-stack PWA for managing and sharing household chores among roommates, built with Cloudflare Workers, D1 Database, and React.

Features

• 🏠 Multiple Homes: Create homes and share join codes (6-character codes) with roommates
• ✅ Chore Management: Create recurring or one-time chores with default effort estimates
• 📅 Calendar View: See who completed what chores on each day
• 📊 Statistics: Track effort by member, chore completion rates, and activity timelines
• 📱 Progressive Web App: Installable on mobile with offline support via service worker
• 🚀 Cloudflare Powered: Runs entirely on Cloudflare Workers and D1 SQLite database

Project Structure

clean-share/
├── src/                      # Cloudflare Workers backend
│   ├── index.ts             # Main API router
│   ├── routes.ts            # Homes and members endpoints
│   ├── chores.ts            # Chores, completions, and schedules endpoints
│   ├── utils.ts             # Helper functions
│   └── types.ts             # TypeScript types
├── frontend/                # React + Vite frontend
│   ├── src/
│   │   ├── api.ts          # API client
│   │   ├── AppContext.tsx   # Global app state
│   │   ├── App.jsx          # Main app component
│   │   └── components/      # React components
│   │       ├── HomeScreen.tsx      # Join/create home screen
│   │       ├── Dashboard.tsx       # Main dashboard with tabs
│   │       ├── ChoreList.tsx       # Chore list and completion
│   │       ├── CalendarView.tsx    # Calendar with activity
│   │       └── Statistics.tsx      # Charts and stats
│   └── public/
│       ├── manifest.json    # PWA manifest
│       └── sw.js           # Service worker
├── migrations/              # Database migrations
│   └── 0001_init_schema.sql # Initial schema
└── wrangler.jsonc          # Cloudflare configuration

Setup

Prerequisites

• Node.js 18+
• Cloudflare account
• Wrangler CLI (installed via npm)

Local Development

1. Install dependencies:

   npm install
   cd frontend && npm install && cd ..

2. Create D1 database (first time):

   wrangler d1 create clean-share --remote
   wrangler d1 execute clean-share --remote --file migrations/0001_init_schema.sql

3. Update database ID in wrangler.jsonc:

   "d1": {
     "bindings": [{
       "binding": "DB",
       "database_name": "clean-share",
       "database_id": "YOUR_DATABASE_ID_HERE"
     }]
   }

4. Run locally:

   npm run dev

   • Backend: http://localhost:8787
   • Frontend (separate): cd frontend && npm run dev (http://localhost:5173)

Deployment

1. Build and deploy:

   npm run deploy

   This builds the frontend and deploys both backend and frontend to Cloudflare.

2. Access your app:

   • Visit https://clean-share.your-account.workers.dev

API Endpoints

Homes

• POST /api/homes - Create home (returns: home data with join code)
• GET /api/homes/:homeId - Get home details with members
• POST /api/homes/join - Join home with code (body: join_code, member_name)

Members

• GET /api/homes/:homeId/members - List members
• GET /api/homes/:homeId/members/:id - Get member
• PUT /api/homes/:homeId/members/:id - Update member

Chores

• GET /api/homes/:homeId/chores - List chores
• GET /api/homes/:homeId/chores/:id - Get chore
• POST /api/homes/:homeId/chores - Create chore
• PUT /api/homes/:homeId/chores/:id - Update chore

Completions

• GET /api/homes/:homeId/completions - List completions (query: member_id, chore_id, from, to)
• POST /api/homes/:homeId/completions - Log completion (body: chore_id, completed_by_member_id, effort_minutes, notes)

Schedules

• GET /api/homes/:homeId/schedules - List upcoming schedules (query: from, to)

Key Concepts

Join Codes

6-character alphanumeric codes for inviting roommates to homes. Generated on home creation.

Chore Repetition

• one_time: Single chore (creates one schedule entry)
• daily: Every day
• weekly: Every 7 days
• biweekly: Every 14 days
• monthly: Every 30 days

On completion, the next schedule is automatically generated based on repetition type.

Effort Tracking

• Each chore has a default effort in minutes
• When completing a chore, you can override the effort
• Statistics aggregate total effort per member and per chore

PWA Features

• Install as app on mobile/desktop
• Offline functionality via service worker
• Network-first caching for API calls with 5-second timeout fallback
• Cache-first for static assets

Development Notes

Adding New Features

1. Backend: Add endpoints in src/ (routes.ts, chores.ts, or new file)
2. Frontend: Add React components in frontend/src/components/
3. Database: Add migrations in migrations/ following the naming convention
4. Update types: Keep src/types.ts and component interfaces in sync

Database Schema

The D1 database includes:

• homes: Home records with join codes
• members: Members of each home
• chores: Chore templates with repetition settings
• chore_completions: Logged completions with actual effort
• chore_schedules: Upcoming chore occurrences

Customization

Colors

Main theme color is #667eea. Update in:

• frontend/src/components/*.css
• wrangler.jsonc (theme_color)
• frontend/public/manifest.json

API Base URL

Set REACT_APP_API_URL environment variable or update in frontend/src/api.ts

Database

Replace database ID in wrangler.jsonc to use different D1 database

Troubleshooting

Frontend not loading: Ensure npm run build:frontend completed successfully and dist/ exists

API errors: Check Network tab in DevTools, verify API endpoints match src/index.ts

Database errors: Ensure D1 database ID is set correctly in wrangler.jsonc

Service worker issues: Clear cache/storage in DevTools, or access in private/incognito window

License

MIT