Chorus

A chore planning and tracking app for a single household, built around a cascading schedule.

Designed for couples and small households who want chores to happen reliably without micromanaging a calendar.

Contents

• Overview
• Key Features
• Deploy Your Own
• Tech Stack
• Project Structure
• Getting Started
• Design Philosophy
• Contributing
• License

Overview

Chorus organizes chores by frequency (daily through yearly, with optional intermediate tiers) and uses a cascading schedule to keep work moving forward. The idea: each level pulls a small amount of work down from the next higher level so nothing gets forgotten.

• Each day: your daily chores + 1 weekly chore
• Each week: your weekly chores + 1 monthly chore
• Each month: your monthly chores + 1 yearly chore

This means 12 yearly chores naturally spread across the year (one per month), 4 monthly chores spread across the weeks, and so on. The system suggests which chore to pull in — prioritizing ones you haven't done in the longest time — but you can always override or pull in extra.

Everything ultimately lands on your daily schedule: you open the app, see what's on your plate today, and check things off.

Deployment Model: Each deployment represents a single household. All users share the same chore pool and can see each other's tasks.

Key Features

• Cascading planning - Higher-frequency chores pull down into lower-frequency slots
• Daily schedule is truth - Everything resolves onto specific days
• Pinned auto-planning - Weekly/biweekly chores can be auto-placed on a preferred weekday
• Smart suggestions - Overdue / never-done chores are prioritized
• Multi-user - Assign chores and see completions per user
• Warnings - Pace/planning warnings when you're falling behind
• Mobile-first UI - Built for quick check-ins and tap targets

Deploy Your Own

Quick Deploy Checklist (Required)

1. Create a free Neon project
2. Enable Neon Auth in the project dashboard and copy the Auth Base URL
3. Generate a cookie secret: openssl rand -base64 32
4. Click the deploy button above and paste NEON_AUTH_BASE_URL and NEON_AUTH_COOKIE_SECRET.
5. Optional onboarding mode: set CHORUS_SIGN_UP_ENABLED=1 so housemates can self-register, then redeploy with it unset/0 to close sign-up.

Fastest Path (Less Copy/Paste)

For the simplest setup, attach Neon Postgres through Vercel during project creation.
Chorus accepts POSTGRES_URL automatically, so you do not need to manually set DATABASE_URL.

Manual Database Path

If you are not using a Vercel Postgres integration, add DATABASE_URL manually from your Neon connection string.

On production deployment, Chorus runs Prisma migrations automatically during the Vercel build (prisma migrate deploy), so a fresh Neon database gets all required app tables in public. Preview deployments skip migrations by design. For best reliability, set MIGRATE_DATABASE_URL in Vercel to a direct Neon connection string (non-pooler host) used only for migrations.

Note: Neon Auth tables in the neon_auth schema are managed by Neon Auth itself, not by Prisma migrations in this repo. Chorus does not auto-seed data during deployment; if you want sample data, run cd web && npx prisma db seed manually.

Post-deploy Checklist

1. Open the deployed site and verify auth pages load.
2. Verify the production build succeeded and migrations were applied.
3. Confirm NEON_AUTH_BASE_URL and NEON_AUTH_COOKIE_SECRET are set in Vercel.
4. Confirm one runtime database variable is present: DATABASE_URL or POSTGRES_URL.
5. Recommended: set MIGRATE_DATABASE_URL (direct Neon host) for production migrations.

Optional post-deploy setup:

• Web push notifications — generate VAPID keys (npx web-push generate-vapid-keys) and add NEXT_PUBLIC_VAPID_PUBLIC_KEY / VAPID_PRIVATE_KEY
• Cron secret — set CHORUS_CRON_SECRET to protect the /api/cron/autoschedule endpoint
• Rate limiting — provision an Upstash Redis instance and add UPSTASH_REDIS_REST_URL / UPSTASH_REDIS_REST_TOKEN

Downstream Deployment Modes

Auto-follow master (recommended)

Use this mode if other deployments should automatically get your latest changes:

1. Deploy with the button above (this creates a GitHub copy in their account and links Vercel to it).
2. Keep Vercel Production Branch set to master.
3. Keep GitHub Actions enabled in that copied repository.
4. Keep .github/workflows/upstream-sync.yml enabled (included in this repo).

How it works:

• The workflow runs every 6 hours (and can also be run manually from Actions).
• It fast-forwards the downstream repository master branch to loehnertz/Chorus master.
• That push triggers a Vercel redeploy.
• Production build runs prisma migrate deploy, so committed migrations are applied automatically.

Manual/custom mode

Use this mode if someone wants to customize code on their own master branch:

1. Disable .github/workflows/upstream-sync.yml in their repo.
2. Pull upstream changes manually when ready.
3. Resolve merge conflicts manually as needed.

Auto-follow Divergence Recovery

If the sync workflow fails, the downstream master branch has diverged from upstream. Choose one path:

1. Keep auto-follow: reset local master to upstream and re-enable sync.
2. Keep local custom commits: disable sync and update manually.

Reset commands for path 1:

git checkout master
git remote add upstream https://github.com/loehnertz/Chorus.git
git fetch upstream master
git reset --hard upstream/master
git push --force-with-lease origin master

Migration Safety Contract (Auto-follow Mode)

• Prefer additive, backward-compatible Prisma migrations.
• Avoid destructive migrations without prior notice to operators.
• Remember: rolling back app code does not automatically roll back database schema.

Tech Stack

• Framework: Next.js (App Router)
• Database: PostgreSQL (Neon)
• ORM: Prisma
• Authentication: Neon Auth (built on Better Auth)
• Styling: TailwindCSS + custom CSS variables
• Animation: Framer Motion
• Testing: Jest + React Testing Library
• Deployment: Vercel

Project Structure

The Next.js application lives in the web/ directory:

chorus/                  # Repository root
├── web/                # Next.js application (work here!)
│   ├── app/           # Next.js App Router pages
│   ├── components/    # React components
│   ├── lib/           # Utilities and shared logic
│   ├── prisma/        # Database schema + migration history
│   └── ...
├── CLAUDE.md          # Development documentation
├── PLAN.md            # Implementation roadmap
└── README.md          # This file

All development work happens in the web/ directory.

Getting Started

Prerequisites

• Node.js 18+ and npm
• Neon account (for database and auth)
• Vercel CLI (optional, for environment sync)

Development Setup

# (Optional) Link to Vercel project (for env sync)
# Run from the repository root (the Vercel project Root Directory is `web`)
vercel link
vercel env pull web/.env.development.local

# Now do all app/dev work in the web directory
cd web

# Install dependencies
npm install

# Or manually set up environment variables
cp .env .env.local
# Edit .env.local with your database and auth credentials

# Set up database and run migrations
npx prisma migrate dev

# Start development server
npm run dev

Visit http://localhost:3001 to see the app.

Environment Variables

Required (see web/.env.example):

• DATABASE_URL or POSTGRES_URL: Postgres connection string
• NEON_AUTH_BASE_URL: Neon Auth base URL
• NEON_AUTH_COOKIE_SECRET: cookie secret

Optional (debug/perf knobs; defaults are off):

• CHORUS_SIGN_UP_ENABLED=1: enables /sign-up and account creation endpoints (/api/auth/sign-up/*); unset/other values disable sign-up
• CHORUS_PROFILE=1: logs coarse timings for auth + autoscheduling
• PRISMA_LOG_QUERIES=1: Prisma query logging (stdout)
• PRISMA_PROFILE_QUERIES=1: logs query durations (stdout)
• PRISMA_SLOW_QUERY_MS=50: logs only queries slower than N ms (implies profiling)
• NEXT_PUBLIC_NAV_PREFETCH=1: enables Next.js Link prefetch in primary nav
• CHORUS_ASYNC_AUTOSCHEDULE=1: schedule view runs auto-scheduling best-effort (non-blocking)

Sign-up toggle workflow for shared households:

1. Deploy with CHORUS_SIGN_UP_ENABLED=1.
2. Have housemates create accounts at /sign-up.
3. Redeploy with CHORUS_SIGN_UP_ENABLED unset (or 0) to disable further sign-ups.
4. Re-enable later when someone new joins.

Cron (optional):

• CHORUS_CRON_SECRET: enables /api/cron/autoschedule (authorize with Authorization: Bearer <secret> or x-chorus-cron-secret: <secret>)

Common Commands

Run all commands from the web/ directory:

cd web  # Always navigate here first!

# Development
npm run dev              # Start development server (port 3001)
npm run build            # Build for production
npm run lint             # Run ESLint
npm run test             # Run unit tests
npm run type-check       # Run TypeScript checks

# Pre-commit workflow (ALWAYS run before committing)
npm run lint && npm run test && npm run build

# Database
npx prisma migrate dev   # Create and apply migrations
npx prisma migrate deploy # Apply committed migrations (used in deploy builds)
npx prisma studio        # Open Prisma Studio GUI
npx prisma generate      # Regenerate Prisma Client

If you change web/prisma/schema.prisma, create and commit a new migration:

cd web
npx prisma migrate dev --name <descriptive_change_name>
git add prisma/migrations prisma/schema.prisma

Design Philosophy

"Domestic Futurism" - A refined, slightly retro-futuristic aesthetic that elevates the mundane task of chores.

• Colors: Terracotta (#E07A5F), Sage (#81B29A), Cream (#F4F1DE), Charcoal (#3D405B)
• Typography: Outfit (display) + Merriweather (body)
• Interactions: Smooth animations, satisfying completion effects

Contributing

This is a personal project, but feedback and suggestions are welcome! Please open an issue to discuss any ideas.

License

See LICENSE file for details.