Hearthin' Home 🔥🏠

Hearthin' Home is a play on "hearth and home" — the hearth is the traditional heart of a house, the place the household actually gathers around — reimagined as the heart of your household's to-do list. It's family/house task management: to-do lists, home and family project tracking, and chore charts, built around the idea that tasks belong not just to a date but to a place.

What it does

• Robust but intuitive scheduling — start date, due date, and a one-tap "push back"/snooze (Later Today / This Evening / Tomorrow / This Weekend / Next Week / custom) that clears an overwhelming list and quietly resurfaces tasks later. A tracked snooze count is a gentle nudge, not a guilt trip.
• Recurrence for chores — completing a recurring task spawns its next occurrence.
• Day constraints & a household holiday calendar — mark a task workdays-only, weekends-only, or just never-on-a-holiday, and its dates, snoozes, and recurring occurrences roll forward to the next day that fits. Each household toggles the 11 US federal holidays individually and adds its own (recurring or one-off) days off.
• Assignees vs. Watchers — assignees are invited or self-assigned and expected to act; watchers just get updates. Displayed as distinct, separate concepts throughout.
• Location-awareness (the headline feature) — Places are first-class: Home, Church, a short-term rental you maintain, physical stores (Home Depot), and Online "stores" (Amazon, eBay). Tasks link to any number of places, and the task list can be filtered three ways: pick a place manually, grant geolocation and let tasks-at-your-location surface automatically, or browse "nearby" with an expanded radius. Shopping lists auto-aggregate per store from your open tasks' checklists.
• Time-dedication scoring — a single door-to-door minute estimate (travel included), bucketed into Quick/Short/Medium/Long/Epic, so you can filter "quick fixes" from "full-day projects."
• Kanban board (Backlog/Ready/In Progress/Blocked/Done) with drag-and-drop, plus strong list views/sort/filter.
• Projects & dependencies — any task with subtasks acts as a project: children are kept inside the parent's start/due window, and moving the parent can shift every descendant's dates with it. Separately, any task can be marked blocked by any other task in the household; blocked tasks stay out of your list until their blockers are done (cycles are rejected, and you can always complete a blocked task anyway).
• Labels, templates, comments/activity, real-time updates (SignalR), optional AI-assisted quick-add (provider-agnostic; Gemini, OpenAI, Anthropic, Ollama or any OpenAI-compatible endpoint, with a per-user "bring your own key" setting), local + Google Sign-In auth, and a per-user ICS calendar feed.
• Theming — Light/Dark/System mode, five color-scheme presets (Hearth/Forest/Ocean/ Plum/Slate) plus a fully custom scheme (pick your own accent color), synced across devices once signed in.

See docs/ROADMAP.md for what's built now vs. planned, and docs/DECISIONS.md for why it's built this way.

Monorepo layout

Path	What
src/	.NET 10 API — modular monolith (Domain/Contracts/Infrastructure/Api)
web/	React + TypeScript + Vite PWA client
deploy/	Docker Compose for self-host and cloud deploy
docs/	Architecture, decisions log, and roadmap
tests/	Automated tests for the API

Quickstart

Prerequisites: .NET 10 SDK, Node.js 22+, Docker (for the full-stack/compose path).

Full stack via Docker Compose

docker compose -f deploy/docker-compose.yml up

Copy deploy/.env.example to deploy/.env first and fill in JWT_SECRET at minimum (see Configuration below). The web app is served at http://localhost:8085.

Local dev loop (hot reload, no Docker)

# Terminal 1 — API (http://localhost:5100)
dotnet run --project src/HearthinHome.Api

# Terminal 2 — web client (http://localhost:5173, proxies /api and /hubs to the API)
cd web
npm install
npm run dev

Apply/update the database schema (PostgreSQL required locally, or point ConnectionStrings__Default at one):

dotnet ef database update --project src/HearthinHome.Infrastructure --startup-project src/HearthinHome.Api

Run the test suite:

dotnet test

Configuration

Environment variables used across the API and web client. The .NET column is the raw double-underscore config key (e.g. for appsettings.json overrides or bare dotnet run); the Compose column is the friendlier name used in deploy/.env / deploy/docker-compose.yml, which maps onto the .NET key for you.

.NET key	Compose var	Purpose
ConnectionStrings__Default	(built from Postgres vars)	PostgreSQL connection string
Jwt__Secret	JWT_SECRET	HMAC-SHA256 signing key for access tokens (32+ chars) — required
Ai__Gemini__ApiKey	GEMINI_API_KEY	Server-wide Google Gemini API key, shared with all members by default; blank means members must bring their own key
Ai__ShareServerKeyWithAllUsers	(same name)	true (default) lets every member use the server key; false reserves it, so AI stays off until a member configures their own provider
Auth__Google__ClientId	GOOGLE_CLIENT_ID	Google OAuth web client id, validates "Sign in with Google" ID tokens
Cors__Origins__0	WEB_ORIGIN	Origin the SPA is served from, added to the API's CORS allow-list
—	POSTGRES_PASSWORD	Postgres superuser password for the bundled database container
VITE_GOOGLE_CLIENT_ID	(web .env, same name)	Google OAuth web client id used by the browser-side Google Identity Services button. Leave unset to hide Google Sign-In entirely and show only the local login form.

The web client reads its own web/.env (copy from web/.env.example); the API reads appsettings.json / appsettings.Development.json plus environment variable overrides.

Self-host vs. cloud

Both paths run the exact same container images (web/Dockerfile → nginx:alpine serving the built SPA and proxying /api//hubs; src/HearthinHome.Api/Dockerfile → the .NET API). Self-hosting is docker compose -f deploy/docker-compose.yml up with a bundled Postgres container. Cloud deploy runs the same two images behind a managed load balancer/ingress and a managed PostgreSQL instance — only the connection string, CORS origin, and secrets differ, all supplied via the environment variables above.

More documentation

• docs/ARCHITECTURE.md — layering, data model, realtime, location-awareness design, AI abstraction, deployment topology.
• docs/DECISIONS.md — ADR-style log of the major technical choices.
• docs/ROADMAP.md — phased feature plan (what's built vs. planned).