HomeBase

Home management for couples and families: shared to-dos, shopping lists per shop, loyalty cards, and read-only calendar sync (iCloud / CalDAV). Built as a mobile-first PWA — one TypeScript codebase end to end.

Layer	Technology
Frontend + Backend	Next.js 15 (App Router) + tRPC v11
Database	PostgreSQL + Prisma
Auth	Auth.js v5 (credentials, JWT sessions)
Styling	Tailwind CSS v4
Calendar sync	CalDAV via tsdav + ical.js
Images	AWS S3 (loyalty card photos, optional in dev)
Hosting	AWS App Runner (Docker)

Local development

# 1. Install
npm install

# 2. Start Postgres
docker compose up -d

# 3. Configure environment
cp .env.example .env.local
# DATABASE_URL=postgresql://homebase:homebase@localhost:5432/homebase
# AUTH_SECRET:            openssl rand -base64 32
# CALDAV_ENCRYPTION_KEY:  openssl rand -hex 32
# AWS_* / S3_BUCKET_NAME: optional — without them, loyalty card photo
#                         upload is disabled (card numbers still work)

# 4. Apply schema
npx prisma migrate deploy   # or: npx prisma db push

# 5. Run
npm run dev

Quality gates: npm run lint and npm run typecheck must pass with zero errors.

Deployment on AWS

The GitHub Actions workflow (.github/workflows/deploy.yml) builds, lints, typechecks, and docker-builds on every push/PR. The deploy job pushes to ECR and triggers App Runner, and only runs on main when the repository variable DEPLOY_ENABLED is set to true.

One-time setup

1. RDS (PostgreSQL) — create a db.t4g.micro instance, note the connection string.
2. S3 — create a private bucket for loyalty card images.
3. ECR — create a repository (e.g. homebase).
4. Secrets Manager — store DATABASE_URL, AUTH_SECRET, and CALDAV_ENCRYPTION_KEY.
5. App Runner — create a service from the ECR image, port 3000. Inject the environment variables from Secrets Manager, plus NEXTAUTH_URL (the public URL), AWS_REGION, and S3_BUCKET_NAME. Use an instance role with s3:PutObject/GetObject/DeleteObject on the bucket instead of static keys where possible.
6. GitHub repository configuration — set the variable DEPLOY_ENABLED=true and the secrets AWS_REGION, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, ECR_REPOSITORY, and APP_RUNNER_SERVICE_ARN.

Database migrations

The container does not run migrations on boot. Apply them when the schema changes, from a machine that can reach RDS:

DATABASE_URL=postgresql://... npx prisma migrate deploy

(If the GitHub runner can reach the database, this can be added as a step in the deploy job before triggering App Runner.)

Environment variables

All variables are documented in .env.example.