Griha

A household chore + finance-tracking platform for three household archetypes (roommates, family, couple) plus a single-person (SOLO) mode, served by one backend to a web app, mobile app, and a tablet "kiosk" client.

This repo is being built in phases against the architecture spec. See the spec doc for the full design. This README only covers what's in the repo right now.

On the name: "Griha" is the only place the product name is hardcoded as a literal string that would need find-and-replace to change (this file, and the root folder itself). Every other technical identifier — the internal package scope (@app/*), Docker container/volume names — is deliberately name-agnostic or driven by one PROJECT_NAME variable in .env, precisely so a future rename doesn't ripple through the codebase. See docs/learning/06-naming-and-configurability.md for the reasoning.

This is Phase 0 + the start of Phase 1 from the roadmap:

• Monorepo skeleton (pnpm workspaces + Turborepo config) — verified: pnpm install and pnpm test run clean
• packages/domain: the household policy engine + task state machine, with unit tests (Phase 1 — the highest-risk business logic, built and tested first, before any API or UI code) — verified: 32/32 passing
• infra/docker/docker-compose.yml: local Postgres + Valkey — verified: both containers report healthy
• CI workflow stub
• Backend API (apps/api) — not started
• Web, mobile, tablet clients — not started

Every "verified" above means what it says: actually run, on a real machine, with the real output checked — not assumed from the code looking right. See docs/learning/DEV-LOG.md for the full account, including two real bugs hit and fixed along the way.

The domain package has no framework, no database, no network dependency — it's pure functions over plain objects. That's deliberate: it's the part of the system where a bug is expensive (wrong payer, wrong split, a minor seeing the wrong task) and cheap to catch with unit tests. Building it first and testing it hard means every later phase (API, web, mobile) sits on a foundation that's already been exercised, instead of discovering business-rule bugs through the UI.

griha/
├── docs/learning/        # concept explainers — see below
├── infra/docker/         # local dev services (Postgres, Valkey)
├── packages/domain/      # pure business logic, framework-agnostic
├── scripts/              # standalone dev/verification scripts
├── .github/workflows/    # CI
├── package.json          # workspace root
├── pnpm-workspace.yaml
└── turbo.json

This project doubles as a learning exercise. docs/learning/ has short explainers for each tool/concept as it's introduced, written for someone who hasn't used it before — what it is, why it was picked here, and what the alternative would have cost. Start at docs/learning/00-overview.md.

docs/learning/DEV-LOG.md is a running, honest log of what happened while this repo was built with an AI coding assistant: what ran, what didn't, what broke, and how it was fixed. It's not a changelog — it's a record of the actual process, including the parts that didn't go smoothly the first time.

See docs/learning/01-pnpm-and-monorepos.md and docs/learning/02-docker-and-containers.md for the why; the short version is in the chat message this repo was delivered with.