Family Greenhouse
A shared plant-care journal for the whole household — a collaborative houseplant tracker with per-plant watering schedules, recurring care tasks (water, fertilize, prune…), and reminders that find the right person in the browser or by email, so nobody has to ask "did you water the Monstera?" ever again.
🌿 Live app (free accounts; paid plans on the web): familygreenhouse.net · 📚 Docs: docs/ · 🧭 Start here: docs/development.md
Commercial status — effective September 1, 2026.
Free account registration is open. Paid plans are available on the web; purchases and plan changes are made by a household admin in Settings.
The dated transitions, and the two gates that control payment activity, are in
docs/COMMERCIAL-STATUS.md.
Built with React + TypeScript on the frontend and AWS Lambda + DynamoDB (single-table) + Cognito on the backend, plus a local Express dev server that mirrors the API surface so you can develop entirely offline — no AWS account or third-party keys required to run it locally.
In loving memory of my mom, Joyce - who taught us to keep growing. 🌱
What's in here
family-greenhouse/
├── frontend/ React + Vite SPA (+ Capacitor iOS/Android shells — docs/mobile.md)
├── backend/ Lambda handlers + a local Express mock that mirrors them
├── infrastructure/ Terraform stack (network, Cognito, DDB, S3, API Gateway, CloudFront)
├── docs/ Detailed docs — start with development.md if you're new
├── scripts/ One-off shell helpers
├── .github/ CI + CD workflows
└── package.json npm workspaces root
Quickstart for developers
You need Node 22+ (see .nvmrc) and npm 10+. From the repo root:
npm install # installs across all workspaces
# Two terminals:
npm --workspace backend run dev # local Express mock at :4000
npm --workspace frontend run dev # Vite dev server at :3000
Open http://localhost:3000 and sign in with [email protected] / password123 — the dev server seeds a household for you on boot.
For everything else (running tests, deploying, configuring channels) follow the deeper docs:
docs/development.md — local dev workflow, where to add a new endpointdocs/architecture.md — how the pieces fit, single-table DDB layout, request lifecycledocs/deployment.md — from-zero AWS deploydocs/testing.md — the test pyramid we run + how to add to itdocs/notifications.md — browser, email and web-push details, and the SMS channel that is built but switched offdocs/billing.md — Stripe integration, plan caps, webhook flowdocs/public-api.md — read-only public API: key auth, scopes, rate limits, endpointsdocs/production-checklist.md — gating list for going livedocs/incidents.md — severity levels, the first 15 minutes, post-mortem templatedocs/runbooks.md — step-by-step fixes (rollback, DDB throttle, Stripe webhooks, PITR…)- — user-issue triage + common resolutions
What works today
Headline features that are wired end-to-end:
- Households: invite-link based, role-aware (admin/member), enforced server-side from the
MEMBER#{userId} membership row — the Cognito custom:household_* claims are defence-in-depth only and are never trusted for authorization (backend/src/middleware/auth.ts)
- Plants: CRUD, photo upload (with S3 presigned URL race-fixed), species autocomplete from a curated catalog, plant-name shuffle, optional Plant.id-powered identification from a photo
- Tasks: types (water/fertilize/prune/repot/custom), recurring frequency, complete/snooze/edit, assigned-to lookups
- Care history: per-plant + household activity feed
- Notifications: browser pop-ups, web push (VAPID) and email (SES), each one configurable per user under Settings → Notifications
- Plan architecture: Seedling/Garden/Greenhouse caps are enforced server-side; paid Garden and Greenhouse plans are sold through Stripe Checkout, and payment creation is fail-closed unless both gates are open —
commercialHoldActive: false in commercial-status.json and PAYMENTS_ENABLED equal to the exact string "1" at runtime (isPaymentActivityAllowed, backend/src/config/commercialStatus.ts)
What needs real infra credentials to leave demo mode is enumerated in docs/production-checklist.md. Every channel/integration falls back gracefully to a structured log line when its env var isn't set, so you don't need a single key to develop locally.
Day-to-day commands
npm test # everything (workspaces)
npm --workspace backend run test:watch # vitest watch on backend
npm --workspace frontend run test:e2e # Playwright (boots both servers)
npm run typecheck # strict TS across both workspaces
npm run lint # eslint across both workspaces
npm run format # prettier
Contributing
Branches off main, conventional-commits style messages, PR with passing CI:
feat(plants): add identification from photo
fix(billing): clamp price-id env lookup
docs: rewrite README
Types we use: feat, fix, docs, style, refactor, perf, test, chore, ci, build, revert. The commitlint hook in .githooks/ will reject anything else.
Standards conformance
This repo is onboarded to the portfolio's STANDARDS/ (vendored at docs/standards/, pinned v3.0.1). State is honest, not aspirational: completed controls name their evidence and residual gaps stay explicit. Full detail (per-control findings, ASVS level, AI-eval waiver, RTF §A–F) lives in docs/RESPONSIBLE-TECH-AUDITS.md; this table is the required top-level declaration (DOC-11/12/13).
| Standard | Applies? | State |
|---|
| Responsible-Tech Framework | Applies (PII + AI) | Partial — §A–F audit, dated DPIA, AI risk register, model card, EU classification, disclosure, and live grounding/privacy controls are committed; ISO 42001 SoA and a published ACR/VPAT remain gaps |
| Code Quality | Applies (TS/Node; Python N/A — no Python code in this repo) | Partial — strict TypeScript, zero-warning ESLint, coverage floors, CODEOWNERS, and branch rules are gated. Backend clears 80% on lines/statements/functions; backend branches (~76%) and all four frontend metrics remain ratcheted below the portfolio's 80% target, tracked under CQ-16/P1-5 |
| Security & Supply-Chain | Applies — ASVS L2 (real PII: emails, phones, photos, household graphs) | Partial — CodeQL, Semgrep, Gitleaks, npm audit, Scorecard, SHA-pinned Actions, and a complete dependency disposition are gated/evidenced; release SBOM, provenance, and signed-tag enforcement remain gaps |
| CI/CD | Applies | Met for current service shape — committed ruleset + CODEOWNERS, strict required checks, OIDC deploys, workflow audit, concurrency, and make verify parity; the ruleset keeps an owner break-glass bypass (note below); production deployment retains its explicit Environment approval |
| Release & Versioning | Applies — tagged releases drive prod deploys | Partial — root/workspace versions are aligned at 0.45.0; tag/version and CHANGELOG gates run at the tagged ref. Release SBOM/provenance and blocking signed-tag verification remain open |
| Observability | Applies — backend ≈ Tier A-adapted (serverless), frontend ≈ Tier B (Web Vitals) | Met for current service shape — 28-day SLO contract, health-excluded RED metrics, burn-rate alerts, X-Ray, first-party browser RUM, release correlation, and regression gate; see ## Observability below |
| Performance | Applies | size-limit, Lighthouse, and the CI bundle-size job enforce the current frontend performance budget |
| Accessibility | Applies | Partial — WCAG 2.2 AA axe coverage spans public and authenticated routes, Lighthouse and keyboard/reflow/reduced-motion gates pass; release-time screen-reader/high-contrast walkthrough and a published ACR/VPAT remain human/external gates |
| Internationalization | Applies (opted in — EN/ES) | Partial — docs/i18n.md, EN/ES key/placeholder/plural/TODO gates, UTF-8 validation, and a hardcoded-string ratchet exist; native-speaker sign-off, pseudolocale overflow, RTL logical-property lint, and remaining literal migration remain |
On the CI/CD row: the committed protect-main ruleset carries exactly one bypass actor — the repository admin role, bypass_mode: always — as the owner's break-glass path. An empty bypass list is not a stricter gate; it removes the only way to repair a wedged main, and GitHub returns 201 when you apply one. That single entry is a deliberate, recorded divergence from the vendored CI-CD-STANDARD.md CICD-15 (PR-only bypass) and §5.1 (empty bypass list) — reasoning, the live-versus-committed state, and the owner-only reconcile command are in .github/rulesets/README.md.
On partial rows: the unresolved work is either protected by the dated AI-evaluation waiver, tied to an external production/account/hardware gate, or named in the corresponding audit with a re-open trigger. Historical remediation notes do not override this current declaration.
Finding IDs. Some code comments and ADRs cite short IDs — CQ-16, CICD-27, DOC-11, P1-5, P2-7. They come from the dated 2026-07-05 conformance audit of this repo and its remediation plan, cited by ADR 0006. The private audit workspace is not part of this repository, so the IDs are traceable labels, not links. CQ-* / CICD-* / DOC-* / RTF-* number per-standard findings; P1-* / P2-* / P3-* number the prioritized remediation items. The one cited most often in code: CQ-16 / P1-5 — coverage floors sit below the CODE-QUALITY standard's 80% target and must ratchet upward release over release instead of staying pinned. That is the policy the thresholds comments in frontend/vitest.config.ts and backend/vitest.config.ts are enforcing.
Observability
Backend: CloudWatch + X-Ray (active tracing on every Lambda invocation), structured JSON logs via pino with requestId/userId/householdId/traceId correlation (utils/logger.ts). Tier: A-adapted for serverless — the OBSERVABILITY-STANDARD's /livez//readyz probes are N/A (no long-lived process to probe; Route53 continuously checks /health). The dashboard and alarms in infrastructure/modules/monitoring/ cover native gateway health, per-route RED signals, Lambda/DynamoDB saturation, DLQs, browser errors, Core Web Vitals, and integration budgets. Application SLO metrics exclude synthetic GET /health traffic.
Frontend: Tier B — Lighthouse remains the lab gate (LCP <2500, CLS <0.1, a11y ≥0.95), and a small first-party RUM rail reports sanitized browser errors plus LCP/CLS/INP to CloudWatch with route and release correlation. It honors Do Not Track and sends no stack traces, query strings, user ids, or free text. Optional Sentry plumbing remains available but is not required for baseline coverage.
The 28-day 99.5% availability, p95 latency, saturation, and frontend-experience objectives are machine-checked in observability/slos.yaml. Operational queries and response steps are in docs/observability.md. OTel/W3C traceparent remains intentionally deferred while the service uses X-Ray-native correlation.
Supported: latest tagged release only (pre-1.0) — see CHANGELOG.md.
License
Elastic License 2.0 — the source is free to read, run, modify, and
self-host for your own household. What it doesn't allow is offering Family
Greenhouse (or a substantial copy of it) to others as a hosted/managed
service. If that's something you want to do, get in touch:
[email protected].
