Houseplant Watering Tracker

Houseplant Watering Tracker — Product & Engineering Specification #

A minimal single-user web app for tracking houseplant watering schedules and reminders.

Overview #

Houseplant owners with several plants on different watering schedules struggle to remember which plants need water and when, which leads to over- and under-watering. This specification describes a deliberately small web app that solves exactly that problem and nothing else: a list of plants, each with a watering interval in days, a one-tap "Watered today" action, and clear highlighting of what is due or overdue right now.

The product is single-user by design. There are no accounts, no photos, no plant species database, and no notifications. Restraint is the design, not a limitation to be engineered around later.

This document is written to be executed cold by an AI coding agent or a small engineering team, without clarifying questions. Every field limit, edge case, error message, and default is decided here. Where a topic is cross-cutting, exactly one section owns it and every other section references it by number; Section 30.2 lists those canonical owners and is the tie-breaker when two passages appear to disagree.

How to read it. Sections are numbered ## and referenced by number throughout. Tables are normative. Code blocks are literal and intended to be used as written. "Must" marks a requirement; "may" marks a permitted option. Section 29 tells the executing agent how to work through the build, and Section 27 gives the milestone order to build it in.

What gets built. One npm workspaces monorepo producing one Docker image: a single Node process serving a React single-page app and a JSON API, backed by one SQLite file on a mounted volume. No managed database, no external service, no third-party network request at runtime.

Table of Contents #

1. Before You Start — Customization Decisions
2. Project Overview and Vision
3. Scope Boundaries
4. Users, Personas and Core Scenarios
5. Technology Stack and Architecture
6. Repository Layout and Coding Conventions
7. Data Model and Database Schema
8. Watering Schedule Domain Logic
9. Validation Rules and Limits
10. Feature: Plant Management
11. Feature: Watering Actions and History
12. Feature: Due and Overdue Status Display
13. API Design and Contract
14. Frontend Information Architecture and Routing
15. Design System and Visual Language
16. Component Architecture and State Management
17. Screen Specifications
18. Interaction States: Loading, Empty, Error, Offline
19. Accessibility Requirements
20. Security, Privacy and Threat Model
21. Configuration and Environment Variables
22. Observability, Logging and Health
23. Performance Budgets and Targets
24. Data Durability: Backup, Export and Import
25. Testing Strategy and Test Matrix
26. Build, Deployment and Operations
27. Milestones and Execution Plan
28. Acceptance Criteria Master Checklist
29. Executor Instructions
30. Appendices

1. Before You Start — Customization Decisions #

This section lists every decision an operator may reasonably want to change before the executing agent begins building. Every decision already has a working default, so none of them block the build. Change any of them by editing the named file or environment variable before first boot; none require a code review beyond that single edit.

1.1 If you change nothing #

The operator gets a single-user app that opens directly to the plant list with no login screen, reachable only by whoever has the URL. It runs on port 8080, computes all watering due-dates in UTC, stores its data in a SQLite file at ./data/app.db inside the container's mounted volume, takes a nightly backup snapshot retained for 14 days, and accepts up to 500 active plants. This is a complete, working deployment — no further configuration is required to use the product as specified in Section 2.

1.2 Prerequisites #

Building and running this project requires exactly:

• Node.js 22 LTS
• npm 10 (ships with Node 22)
• Docker 24 or newer — optional, only needed for the container build and deploy path described in Section 26; the app also runs directly under Node for local development.
• A machine or container with at least 256 MB of RAM free at runtime.

Nothing else. No cloud account, no external service subscription, no third-party API key, and no network access is required to build, test, or run the application.

2. Project Overview and Vision #

2.1 What the product is #

The Houseplant Watering Tracker is a minimal single-user web application that tracks watering intervals for a personal houseplant collection and shows which plants need water today. It replaces memory and guesswork with a short list an owner can check in seconds from a phone. It does one job — answering "which plants need water right now" — and deliberately does nothing else.

2.2 The problem #

An owner with more than a handful of plants is tracking several independent schedules at once: a fern that wants water every four days, a succulent that wants it every three weeks, a fiddle-leaf fig somewhere in between. Nothing about a shelf of plants signals which of them is due. The owner is left relying on memory, a rough sense of "it's been a while," or a habit of watering everything on the same day regardless of what each plant actually needs. The failure modes are symmetric and both damaging: forgetting a plant leads to under-watering and eventual wilting or death; watering out of caution when nothing is due leads to over-watering, root rot, and the same outcome by a different path. The underlying problem is not a lack of care — it is a lack of a simple, glanceable reference that says, per plant, "due in 3 days" or "2 days overdue." This product is that reference and nothing more.

2.3 The product principle: restraint #

The customer asked for a deliberately small application, and the smallness is the specification, not a starting point to be expanded. Every feature in Section 3.1 is fully specified end to end; every capability in Section 3.2 is out of scope and must stay out of scope. An executing agent must not add accounts, notifications, photo storage, species databases, analytics dashboards, or any other feature that was deliberately excluded, even if it seems like a natural or low-cost extension. Where a requirement is silent on a point, the correct instinct is to choose the smallest option consistent with the stated rules (see Section 3.4), never the most feature-complete one. Restraint is a deliverable, and depth of specification for the small feature set is preferred over breadth across a larger one.

2.4 Success definition #

The build is successful when all of the following are true and verifiable:

1. A new plant can be added, with name and interval, in under 15 seconds on a phone-sized screen, measured from tapping "Add plant" to the plant appearing in the list.
2. The answer to "what needs water today" is readable within 3 seconds of the list finishing its first render, without scrolling, on a 360px-wide viewport, for a collection of up to 20 plants.
3. Marking a plant watered is a single tap and requires no confirmation dialog, no navigation away from the list, and completes its visible state change within 250 ms of the tap under normal network conditions (the hard limit in Section 23.2).
4. The system holds zero server-side state beyond one SQLite file; deleting that file and restarting the process returns the app to a genuinely empty first-run state with no orphaned state elsewhere.
5. A plant's overdue status never silently clears itself; it changes only in response to an explicit watering action recorded against that plant (see Section 8.6).
6. The full test suite (Section 25) passes in CI on every commit to the main branch before a build is considered releasable.
7. The entire application — API and static frontend — runs from a single Docker image and a single Node process, with no additional service, database server, or background worker to operate.
8. An operator can go from a clean checkout to a running instance using only the steps in Section 26, with no manual step outside the documented build and start commands.

2.5 The shipping artifact #

The product ships as a single Docker image built from the multi-stage Dockerfile at the repository root (Section 26). Running that image starts one Node.js process that serves both the JSON API under /api/v1 and the built static frontend from the same HTTP listener on the configured PORT (Section 21). All persistent state lives in one SQLite database file at APP_DATABASE_PATH, which the operator mounts as a volume so it survives container restarts. There is no second container, no managed database, and no external dependency required at runtime.

2.6 What this product is not #

The product deliberately does not provide, and must never be extended to provide:

• Multi-user accounts, logins, roles, or any form of shared or collaborative plant list.
• Photo uploads or an image gallery for plants.
• A built-in plant species database, care guide content, or species-specific watering suggestions.
• Email, push, or SMS notifications of any kind.
• Weather data or environmental sensor integrations (soil moisture, humidity, light).
• A native iOS or Android application, or any app-store presence.
• Watering history analytics, charts, trends, or reporting beyond the current due/overdue status shown in the list.

3. Scope Boundaries #

3.1 In scope #

Every core feature is built completely. The table below maps each one, plus the supporting capabilities the product needs to operate as a deployable service, to the section that specifies it in full.

3.2 Out of scope #

The following are never built, and never partially built as a stepping stone toward a future version:

3.3 Deliberate non-requirements #

These are capabilities a competent engineer might assume belong in a "real" production web application. They are intentionally absent from this one, for the stated reason in each case.

3.4 Scope change protocol #

The executing agent does not add scope. When an implementation decision is not explicitly covered by this specification, the agent resolves it by choosing the simplest option consistent with the restraint principle (Section 2.3), the confirmed out-of-scope list (Section 3.2), and the canonical technical decisions already fixed elsewhere in this document, and records that decision in the decision log (Section 30). The agent never treats an unlisted behavior as an invitation to design a new feature, and never defers a required behavior with a placeholder; every gap is closed by a stated, recorded decision before the milestone containing it is considered complete (Section 27).

4. Users, Personas and Core Scenarios #

4.1 The single persona #

There is exactly one persona, because there is exactly one user role in this product.

Profile: An adult houseplant owner with somewhere between 5 and 40 plants spread around a home. They are not a developer and not technical beyond ordinary smartphone use. They check the app most mornings from their phone, and occasionally from a laptop when adding several new plants at once after a shopping trip.

Goals:

• Know, at a glance, which plants need water today without inspecting each plant individually.
• Record that a plant has been watered with minimal friction, ideally one tap, while their hands may be wet or holding a watering can.
• Trust that an "overdue" plant stays visibly overdue until they actually deal with it.

Frustrations this product removes:

• Forgetting which plants were on a longer cycle and over-watering them out of caution.
• Losing track after a trip and not knowing how overdue anything is.
• Having to open a spreadsheet or note app that was not built for this and requires manual date arithmetic.

Environment of use: Often standing in a hallway or by a windowsill, one hand occupied by a watering can, using a phone one-handed on an ordinary home Wi-Fi connection that is sometimes slow or briefly drops. The interface must be usable at arm's length, in this posture, without precision tapping or multi-step confirmation flows.

4.2 Access model #

There are no roles and no accounts. The single person using the app to check on plants and the single person who deployed it are conceptually the same individual wearing two different hats: the "user" hat when checking or watering plants, and the "operator" hat only at deploy time, when they choose the timezone, the port, and whether to turn on the optional access code. The application itself has no concept of identity — every request that reaches it is treated as the one legitimate user. What that means in practice for exposure and hardening is specified in full in Section 20; this section only establishes that the product's data model and UI never ask "who is this."

4.3 Core scenarios #

Each scenario is a complete, testable, end-to-end journey. "System response" describes observable behavior; "Section reference" points to where that behavior is specified in full.

4.3.1 First run with an empty list #

4.3.2 Adding the first plant #

4.3.3 The daily morning check #

4.3.4 Watering one plant #

4.3.5 Watering several plants in a row #

4.3.6 Correcting a mis-tap with Undo #

4.3.7 Editing an interval after realizing a plant drinks faster #

4.3.8 Deleting a plant that died #

4.3.9 Returning after a two-week holiday to several overdue plants #

4.3.10 Adding a plant that was last watered three days ago #

4.4 Anti-scenarios #

Things the user may try, and what the product deliberately shows instead, because these behaviors are out of scope per Section 3.2:

5. Technology Stack and Architecture #

This product is built for exactly one concurrent user operating a small, bounded dataset from at most one or two devices at a time. That constraint is the reason for every architectural choice below: a single Node process, a single embedded SQLite file, no cache layer, no queue, and no separate services. Anything heavier than this — a client-server database, a job queue, a second process — would add operational surface area without solving a problem this product actually has. This rationale is stated once here and is not repeated in the sections that reference it.

5.1 Stack table #

5.2 Runtime topology #

                     ┌───────────────────────────┐
                     │   Operator's reverse proxy │   (TLS termination, optional —
                     │   or direct exposure       │    out of scope, named in 5.3)
                     └──────────────┬────────────┘
                                    │  HTTP
                                    ▼
┌──────────────────────────────────────────────────────────────────┐
│                     Single Node.js 22 process                    │
│                                                                    │
│   ┌───────────────────────────┐   ┌────────────────────────────┐ │
│   │  Fastify HTTP server      │   │  In-process maintenance     │ │
│   │  - /api/v1/*  (JSON API)  │   │  timers:                    │ │
│   │  - /*         (static SPA)│   │  - soft-delete purge (24h)  │ │
│   └─────────────┬─────────────┘   │  - nightly backup snapshot  │ │
│                 │                  └──────────────┬─────────────┘ │
│                 ▼                                  ▼               │
│         ┌──────────────────────────────────────────────┐         │
│         │        better-sqlite3 connection (WAL)         │         │
│         └──────────────────────┬───────────────────────┘         │
└────────────────────────────────┼──────────────────────────────────┘
                                   ▼
                     ┌───────────────────────────┐
                     │  SQLite file on a mounted  │
                     │  volume: APP_DATABASE_PATH │
                     └───────────────────────────┘

There is no separate web server, no cache layer (e.g. Redis), no message queue, and no background worker process distinct from the process shown above. The "maintenance timers" are setInterval/ setTimeout callbacks inside the same event loop, not separate processes (Section 24, Section 9).

5.3 Request lifecycle #

A single request is handled end to end as follows:

1. TLS termination happens, if at all, at the operator's own reverse proxy in front of the container; this application never terminates TLS itself and is named here only to be explicit that it is out of scope (Section 26 covers the recommended deployment pattern).
2. Connection reaches Fastify on APP_HOST:PORT.
3. Request-id assignment: Fastify's built-in genReqId assigns a UUIDv7 request id, attached to the logger context and echoed as requestId in any error response (Section 13).
4. Route matching: Fastify matches the method and exact path (ignoreTrailingSlash: false, Section 13). No match → 404 NOT_FOUND. Path matches but method does not → 405 METHOD_NOT_ALLOWED.
5. Content-Type check: for requests with a body, the media type must be application/json; a charset=utf-8 parameter is permitted and any other media type yields → 415 UNSUPPORTED_MEDIA_TYPE.
6. Body size cap enforcement: 64 KB for normal endpoints, 5 MB for the import endpoint (Section 13, Section 24); exceeding it → 413 PAYLOAD_TOO_LARGE.
7. JSON parse: malformed JSON → 400 MALFORMED_JSON.
8. Zod validation against the shared schema for that endpoint (Section 9); unknown fields are stripped, not rejected; validation failures → 400 VALIDATION_FAILED with a populated details array.
9. Repository call: the route handler calls a repository function in apps/api/src/db/, never touching the raw connection directly (Section 6.7).
10. Synchronous SQLite statement execution: better-sqlite3 executes the prepared statement synchronously within the handler; because this blocks the event loop, statements are kept small and indexed (Section 7) so this never becomes a bottleneck at this data scale.
11. DTO mapping: the repository or a mapper layer converts snake_case rows to camelCase DTOs (Section 3, Section 6.4); raw rows never reach the route handler's response.
12. Domain computation: for plant reads, the shared schedule functions (Section 8) compute status, nextDueOn, daysUntilDue, and daysOverdue from the stored dates.
13. Response envelope construction: success responses use the canonical envelope (Section 13); the handler sets the correct status code (200/201/204).
14. Logging: pino logs one structured line per request with requestId, method, path, status code, and duration in milliseconds (Section 22); request and response bodies containing notes are never logged (Section 20).
15. Unhandled errors: any error not raised as an AppError (Section 6.6) is caught by the global error handler, logged with its stack trace server-side only, and returned to the client as 500 INTERNAL_ERROR with no internal detail leaked in the message.

5.4 Static asset serving #

The same Fastify process serves the built frontend using @fastify/static, pointed at apps/web/dist. Routing rules:

• Any request path beginning with /api/ is never treated as a static asset request.
• Any other GET request whose path does not match a file in dist is rewritten to index.html (SPA fallback), so client-side routes (Section 14) resolve correctly on a hard refresh or direct link.
• Non-GET requests to non-/api paths return 405 METHOD_NOT_ALLOWED.
• Cache headers: hashed, content-addressed build assets (JS/CSS bundles emitted by Vite with a content hash in the filename) are served with Cache-Control: public, max-age=31536000, immutable. index.html is served with Cache-Control: no-cache so a new deployment is always picked up on next load without requiring the user to hard-refresh.

5.5 Data flow for the schedule computation #

Watering status is always computed server-side, on every read, from the two stored facts — lastWateredOn and wateringIntervalDays — using the pure functions specified in full in Section 8. It is never persisted as a column. A stored status value would go stale the instant the clock crossed local midnight in APP_TIMEZONE without any write happening to the row, so storing it would require a separate process just to keep it correct — exactly the kind of background worker this architecture avoids (Section 5.2). Computing it fresh on every read is both simpler and always correct. The client may recompute the same values optimistically between fetches using the identical shared pure functions (Section 8.5), but the server's value on the next fetch is authoritative, and the refresh triggers in Section 16.5 (window focus, visibility change, local-midnight timer, 5-minute background poll, and post-mutation invalidation) exist specifically to keep the client's optimistic view from drifting far from that authoritative value.

5.6 Concurrency model #

The product is built for a single user, but its concurrency behavior is fully defined rather than left implicit:

• SQLite runs in WAL mode for better read/write concurrency within the process.
• busy_timeout is set to 5000 ms, so a rare lock contention within the same process waits rather than failing immediately.
• synchronous = NORMAL — durable enough for this workload without the full fsync cost of FULL, consistent with the "not sensitive data" classification in Section 20.
• The API holds one shared better-sqlite3 connection for the process lifetime; it is not pooled, because better-sqlite3 is synchronous and a pool would add complexity without benefit for a single connection.
• Because better-sqlite3 executes queries synchronously on the main thread, route handlers must never perform slow synchronous work (large loops, heavy computation) inline; all statements in this product operate on small, indexed result sets (Section 7) so this is never a practical concern at the stated 500-plant cap.
• Two-tab / two-device conflict policy: if the same plant is edited from two sessions at nearly the same time, the last write wins. There is no locking or merge logic. Every plant DTO includes an updatedAt timestamp; write endpoints accept an optional optimistic-concurrency header as specified in Section 10.5, and a client that detects a conflict simply refetches and re-renders — there is no blocking conflict-resolution UI, consistent with the single-user assumption in Section 4.1.

5.7 Third-party dependency inventory #

Every runtime and development dependency used anywhere in this specification appears here. No later section introduces a package not listed in this table.

5.8 Explicitly rejected alternatives #

6. Repository Layout and Coding Conventions #

This section is canonical for the repository's directory structure and every coding convention used throughout the codebase. Other sections reference it by number rather than restating any of it.

6.1 Directory tree #

houseplant-tracker/
├── package.json                  # npm workspaces root — see 6.2
├── tsconfig.base.json             # shared compiler options — see 6.3
├── eslint.config.js                # flat config — see 6.5
├── .prettierrc.json               # formatting rules — see 6.5
├── Dockerfile                     # multi-stage build — see Section 26
├── docker-compose.yml             # local/prod compose file — see Section 26
├── .env.example                   # documents every var in Section 21, no real secrets
├── .gitignore                     # see 6.8
├── README.md                      # operator quick-start, links into this spec
├── packages/
│   └── shared/
│       ├── package.json           # name: "@houseplant/shared"
│       ├── tsconfig.json          # extends ../../tsconfig.base.json
│       └── src/
│           ├── index.ts           # public barrel export (the ONE allowed barrel, see 6.5)
│           ├── schemas/           # Zod schemas — plant.schema.ts, watering.schema.ts, pagination.schema.ts
│           ├── types/             # inferred TS types + API DTOs — plant.types.ts, watering.types.ts, api.types.ts
│           ├── domain/            # pure watering-schedule logic — schedule.ts (Section 8),
│           │                      #   calendar-date.ts, errors.ts (+ colocated .test.ts)
│           └── constants.ts       # MAX_ACTIVE_PLANTS, PURGE_AFTER_DAYS, DUE_SOON_THRESHOLD_DAYS, error codes
├── apps/
│   ├── api/
│   │   ├── package.json           # name: "@houseplant/api"
│   │   ├── tsconfig.json          # extends ../../tsconfig.base.json
│   │   ├── migrations/            # 0001_init.sql — see Section 7.10
│   │   └── src/
│   │       ├── index.ts           # process bootstrap: load config, build server, listen
│   │       ├── server.ts          # buildServer() -> FastifyInstance, registers all plugins/routes
│   │       ├── config.ts          # env parsing with Zod — the canonical implementation of Section 21
│   │       ├── db/
│   │       │   ├── connection.ts  # single better-sqlite3 connection, WAL pragmas — see 5.6
│   │       │   ├── migrate.ts     # migration runner against schema_migrations
│   │       │   └── repositories/  # plants.repository.ts, waterings.repository.ts, settings.repository.ts
│   │       ├── routes/
│   │       │   ├── plants.ts      # /api/v1/plants*
│   │       │   ├── waterings.ts   # /api/v1/plants/:plantId/waterings*
│   │       │   ├── meta.ts        # /api/v1/meta — see Section 13.5.10
│   │       │   ├── health.ts      # /api/v1/health — see Section 22
│   │       │   └── backup.ts      # /api/v1/export, /api/v1/import — see Section 24
│   │       ├── plugins/
│   │       │   ├── error-handler.ts     # maps AppError -> canonical error envelope, see 6.6
│   │       │   ├── request-id.ts        # UUIDv7 request id assignment
│   │       │   ├── rate-limit.ts        # wraps @fastify/rate-limit with APP_RATE_LIMIT_* config
│   │       │   ├── security-headers.ts  # Helmet-equivalent headers and the CSP — see Section 20
│   │       │   └── static-files.ts      # wraps @fastify/static per Section 5.4
│   │       └── lib/
│   │           ├── access-code.ts     # optional unlock-screen logic — see Section 20
│   │           ├── backup.ts          # nightly VACUUM INTO snapshot job — see Section 24
│   │           ├── backup-verify.ts   # snapshot integrity and row-count verification — see Section 24
│   │           ├── purge.ts           # soft-delete purge timer — see Section 9
│   │           ├── export.ts          # GET /api/v1/export implementation — see Section 24
│   │           ├── import.ts          # POST /api/v1/import implementation — see Section 24
│   │           ├── zod-error.ts       # maps a ZodError to AppError details — see 6.6
│   │           └── logger.ts          # pino instance construction — see Section 22
│   └── web/
│       ├── package.json           # name: "@houseplant/web"
│       ├── tsconfig.json          # extends ../../tsconfig.base.json
│       ├── vite.config.ts
│       ├── index.html
│       └── src/
│           ├── main.tsx           # ReactDOM root, providers (QueryClientProvider, RouterProvider)
│           ├── App.tsx            # top-level layout shell
│           ├── routes/            # route components — see Section 14
│           ├── components/        # PlantList, PlantRow, PlantForm, StatusBadge, ... — see Section 16
│           ├── hooks/             # usePlants, useWaterPlant, useTheme, ... — see Section 16
│           ├── api/                # typed fetch client wrapping /api/v1, one function per endpoint
│           ├── styles/
│           │   └── tokens.css     # CSS custom properties — see Section 15
│           └── lib/
│               ├── sort.ts        # SORT_ORDERS and the name/recently-watered comparators — see Section 12.3
│               └── theme.ts       # localStorage-backed theme override — see Section 15
└── e2e/
    ├── fixtures/                  # seeded-database fixtures for Playwright
    └── specs/                     # journey specs mirroring Section 4.3 scenarios

6.2 Workspace configuration #

The root package.json declares the workspaces and every cross-cutting script an operator or CI job runs:

{
  "name": "houseplant-tracker",
  "private": true,
  "version": "1.0.0",
  "type": "module",
  "engines": {
    "node": ">=22.0.0",
    "npm": ">=10.0.0"
  },
  "workspaces": [
    "packages/*",
    "apps/*"
  ],
  "scripts": {
    "dev": "npm run dev --workspace=apps/api & npm run dev --workspace=apps/web",
    "build": "npm run build --workspace=packages/shared && npm run build --workspace=apps/api && npm run build --workspace=apps/web",
    "test": "vitest run",
    "test:unit": "vitest run --project unit",
    "test:api": "vitest run --project api",
    "test:coverage": "vitest run --coverage",
    "test:e2e": "playwright test",
    "test:a11y": "playwright test --grep @a11y",
    "lint": "eslint .",
    "format": "prettier --write .",
    "format:check": "prettier --check .",
    "typecheck": "npm run typecheck --workspaces --if-present",
    "migrate": "npm run migrate --workspace=apps/api",
    "seed": "npm run seed --workspace=apps/api",
    "size-check": "node scripts/check-bundle-size.mjs"
  }
}

The root package declares "type": "module" so every workspace's own build output is loaded as ESM by default; better-sqlite3 is a CommonJS native addon and is imported in apps/api via its default interop (import Database from 'better-sqlite3'), which Node's ESM loader supports without a createRequire shim.

6.3 TypeScript configuration #

tsconfig.base.json at the repository root, extended by every package's own tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2023",
    "lib": ["ES2023"],
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true,
    "noImplicitOverride": true,
    "noFallthroughCasesInSwitch": true,
    "forceConsistentCasingInFileNames": true,
    "skipLibCheck": true,
    "esModuleInterop": true,
    "resolveJsonModule": true,
    "isolatedModules": true,
    "paths": {
      "@shared/*": ["../../packages/shared/src/*"]
    }
  }
}

apps/api/tsconfig.json and apps/web/tsconfig.json each extend this file, adding only the outDir, rootDir, and (for apps/web) the jsx: "react-jsx" and DOM lib entries specific to that app. packages/shared/tsconfig.json extends it with declaration: true so both apps consume typed output. The @shared/* path alias is the only cross-package import path; nothing imports packages/shared via a relative ../../ path.

6.4 Naming conventions #

6.5 Code style rules #

ESLint 9 flat config (eslint.config.js) at the repository root:

// eslint.config.js
import js from '@eslint/js';
import tseslint from 'typescript-eslint';
import reactHooks from 'eslint-plugin-react-hooks';

export default tseslint.config(
  js.configs.recommended,
  ...tseslint.configs.strict,
  {
    files: ['apps/web/**/*.{ts,tsx}'],
    plugins: { 'react-hooks': reactHooks },
    rules: {
      ...reactHooks.configs.recommended.rules,
    },
  },
  {
    rules: {
      '@typescript-eslint/no-explicit-any': 'error',
      'no-restricted-imports': 'error', // rule sets configured per-workspace, see 6.7
      'import/no-default-export': 'off', // overridden per-file for React route components only
    },
  },
  {
    ignores: ['**/dist/**', '**/node_modules/**', '**/coverage/**', '**/playwright-report/**'],
  }
);

.prettierrc.json:

{
  "semi": true,
  "singleQuote": true,
  "trailingComma": "all",
  "printWidth": 100,
  "tabWidth": 2
}

Non-negotiable rules beyond what the configs above enforce mechanically:

1. No any without an inline // justified: <reason> comment on the same line; the ESLint rule is set to error, and a suppression must explain itself.
2. No default exports, except React route components (Section 14 requires the router to consume a default export). Every other module uses named exports.
3. No barrel files deeper than packages/shared/src/index.ts. Nothing else in the repository re-exports through an index.ts aggregator.
4. Functions over classes, except for repository objects in apps/api/src/db/repositories/, which are plain object literals of functions grouped by table, not classes — "repository objects" refers to that grouping, not to instantiable classes.
5. Errors are thrown only as typed AppError instances (Section 6.6); no route or domain function throws a bare Error or a string.

6.6 The AppError contract #

Every layer of the application signals a handled failure by throwing this class, defined once in packages/shared/src/domain/errors.ts and imported by both apps:

export interface AppErrorDetail {
  path: string;
  message: string;
}

export interface AppErrorParams {
  code: string;
  httpStatus: number;
  message: string;
  details?: AppErrorDetail[];
  cause?: unknown;
}

export class AppError extends Error {
  readonly code: string;
  readonly httpStatus: number;
  readonly details?: AppErrorDetail[];
  readonly cause?: unknown;

  constructor(params: AppErrorParams) {
    super(params.message);
    this.name = 'AppError';
    this.code = params.code;
    this.httpStatus = params.httpStatus;
    this.details = params.details;
    this.cause = params.cause;
  }
}

code must be one of the canonical error codes and httpStatus must be its paired status, both defined in Section 13. apps/api/src/plugins/error-handler.ts catches every AppError thrown from a route or repository and maps its fields directly onto the canonical error envelope from Section 13; any thrown value that is not an AppError instance is treated as an unexpected failure and mapped to 500 INTERNAL_ERROR as described in Section 5.3, step 15.

6.7 Module boundary rules #

These boundaries are enforced by ESLint's no-restricted-imports, configured per workspace. The rule for apps/web (the pattern for apps/api mirrors it with the paths reversed):

// apps/web/eslint.config.js addition
{
  rules: {
    'no-restricted-imports': [
      'error',
      {
        patterns: [
          {
            group: ['**/apps/api/**', '@houseplant/api', '@houseplant/api/*'],
            message: 'apps/web must never import from apps/api. Go through the HTTP API instead.',
          },
          {
            group: ['**/db/connection*'],
            message: 'Import a repository from db/repositories instead of the raw connection.',
          },
        ],
      },
    ],
  },
}

A violation of any row in the table above fails npm run lint and therefore fails CI (Section 26).

6.8 Git conventions #

• Branch naming: <type>/<short-kebab-description>, e.g. feat/plant-list, fix/overdue-day-math, chore/eslint-config. <type> matches the Conventional Commits type list below.
• Commit messages: Conventional Commits. Allowed types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert. Example: feat(api): add watering idempotency check.
• Commit granularity: at minimum, one commit per milestone as defined in Section 27; commits within a milestone may be finer-grained, but the milestone's exit criteria must be met by its final commit.
• .gitignore:
  Copy

  node_modules/
  dist/
  data/
  *.db
  *.db-journal
  *.db-wal
  *.db-shm
  .env
  coverage/
  playwright-report/
  test-results/

6.9 Comment and documentation policy #

Every exported function in packages/shared carries a JSDoc block describing its parameters, return value, and any non-obvious invariant (for example, the calendar-arithmetic guarantees in Section 8). Code in apps/api and apps/web does not require JSDoc on every export, but any function whose behavior is not obvious from its name and types gets one. In both cases, comments exist to explain why a piece of code does something non-obvious — a tradeoff, an edge case, a rule from this specification — never to restate what the code visibly already does.

7. Data Model and Database Schema #

7.1 Entity overview #

┌─────────────────────┐         ┌──────────────────────┐
│       plants         │ 1     * │       waterings       │
│───────────────────────│─────────│────────────────────────│
│ id (PK)               │◄────────│ plant_id (FK)          │
│ name                   │         │ id (PK)                │
│ watering_interval_days │         │ watered_on              │
│ notes                  │         │ created_at              │
│ last_watered_on        │         └──────────────────────┘
│ created_at             │
│ updated_at             │
│ deleted_at              │
└─────────────────────┘

┌─────────────────────┐         ┌──────────────────────────┐
│      settings        │         │    schema_migrations       │
│───────────────────────│         │────────────────────────────│
│ key (PK)               │         │ version (PK)                │
│ value                  │         │ name                        │
│ updated_at             │         │ applied_at                  │
└─────────────────────┘         │ checksum                    │
                                  └──────────────────────────┘

plants is the single record of every houseplant the owner tracks. Each row is the plant's identity (name), its schedule input (watering_interval_days), its schedule anchor (last_watered_on), and optional free text (notes). A plant is never physically removed by normal use; it is soft-deleted (deleted_at) and later purged (Section 7.8).

waterings is the append-only event log of watering actions. One plant has many waterings; one watering row belongs to exactly one plant, enforced by the plant_id foreign key. plants.last_watered_on is a denormalised cache of the most recent waterings.watered_on for that plant — it exists so every read of the schedule (Section 8) is a single-row lookup with no join, at the cost of the repository layer being responsible for keeping the two in sync (Section 7.13).

settings is a single-row-per-key store for small pieces of server-generated or operational state that are not part of the plant domain and do not belong in an environment variable (Section 21).

schema_migrations records which migration files have been applied, in order, with an integrity checksum. It is the only table the migration runner itself manages outside the numbered migration files (Section 7.10).

Cardinality summary: plants (1) — (0..*) waterings. settings and schema_migrations are independent single-purpose tables with no foreign keys to or from plants or waterings.

7.2 SQLite configuration #

The following pragmas are executed on every connection open, in apps/api/src/db/connection.ts, immediately after the better-sqlite3 Database instance is constructed and before any other statement runs:

foreign_keys = ON is a per-connection setting, not a database-file setting. SQLite does not persist it. If the connection bootstrap code is ever changed and this pragma is dropped, every foreign key constraint in Section 7.3–7.4 silently stops being enforced — no error is raised, rows simply stop being validated. The connection module must set this pragma unconditionally on every Database open, including in test setup and the migration runner, and a test in Section 25 asserts PRAGMA foreign_keys returns 1 on a freshly opened connection.

Because the process model is a single Node process with a single better-sqlite3 connection (Section 5.1 — one process, one user, one writer), no connection pool is used; these four pragmas are set exactly once at process start.

7.3 plants table #

CREATE TABLE plants (
  id                      TEXT PRIMARY KEY,
  name                    TEXT NOT NULL,
  watering_interval_days  INTEGER NOT NULL,
  notes                   TEXT NULL,
  last_watered_on         TEXT NOT NULL,
  created_at              TEXT NOT NULL,
  updated_at              TEXT NOT NULL,
  deleted_at              TEXT NULL,
  CHECK (watering_interval_days BETWEEN 1 AND 365),
  CHECK (length(trim(name)) BETWEEN 1 AND 60),
  CHECK (notes IS NULL OR length(notes) <= 2000),
  CHECK (last_watered_on GLOB '[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]')
);

The four CHECK constraints are the last line of defence against a bug that bypasses the application layer (a bad migration, a manual sqlite3 session, a future integration). They are deliberately loose: the last_watered_on GLOB pattern verifies the four-digit/two-digit/two-digit shape but not that the date is a real calendar date (it would accept 2026-13-40). Real calendar-date validity, Unicode normalisation, and control-character stripping are enforced once, in the shared Zod schemas (Section 9), which is the primary and authoritative validation layer. The database never trusts input it has not already been validated by the API.

7.4 waterings table #

CREATE TABLE waterings (
  id          TEXT PRIMARY KEY,
  plant_id    TEXT NOT NULL REFERENCES plants(id) ON DELETE CASCADE,
  watered_on  TEXT NOT NULL,
  created_at  TEXT NOT NULL,
  CHECK (watered_on GLOB '[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]')
);

CREATE UNIQUE INDEX uq_waterings_plant_date ON waterings(plant_id, watered_on);

The uq_waterings_plant_date unique index on (plant_id, watered_on) is what makes the "Watered today" action idempotent at the storage layer, independent of any application-level check: a second insert attempt for a plant already watered on a given calendar date raises a SQLite UNIQUE constraint failed error, which the repository layer (Section 7.13) catches and turns into the idempotent "already watered today" response (Section 11.2) rather than propagating as a server error.

7.5 settings table #

CREATE TABLE settings (
  key         TEXT PRIMARY KEY,
  value       TEXT NOT NULL,
  updated_at  TEXT NOT NULL
);

settings is a plain key/value store. value is always stored as TEXT; a key whose logical type is a number or boolean stores its string representation, and the reading code owns the parse. The complete, closed set of keys the application ever writes:

No other key may be introduced without adding a row to this table in this specification. A row for a key not in this table is a bug and must fail a Section 25 test that enumerates SELECT key FROM settings against this exact list.

7.6 schema_migrations table #

CREATE TABLE schema_migrations (
  version      INTEGER PRIMARY KEY,
  name         TEXT NOT NULL,
  applied_at   TEXT NOT NULL,
  checksum     TEXT NOT NULL
);

This table is created by the migration runner itself, not by a numbered migration file. The runner's bootstrap step is CREATE TABLE IF NOT EXISTS schema_migrations (...) executed directly by apps/api/src/db/migrate.ts before it reads the migrations/ directory. This avoids the chicken-and-egg problem of the first numbered migration needing a schema_migrations row recorded in a table that migration itself would otherwise have to create.

Checksum guard: every time the process starts, the runner recomputes the SHA-256 of every migration file already recorded as applied and compares it against the stored checksum. If any previously applied file's contents no longer match its recorded checksum, the process logs the exact filename and the two checksums, then exits with code 78 (configuration error, matching Section 21's convention) without attempting to apply any further migrations. This makes silently hand-editing an already-applied migration file impossible to do without the mismatch being caught on the next boot.

7.7 Index inventory #

At the product's hard cap of 500 plants and a worst case of a few thousand watering rows per plant over many years (Section 7.12), SQLite's query planner would produce acceptable plans via full table scans alone; at this scale these indexes are close to irrelevant for raw speed. They exist for correctness (the UNIQUE index is a data-integrity constraint, not an optimisation) and as a safety margin if the 500-plant cap is ever revisited.

7.8 Referential integrity and delete behaviour #

• Plants soft-delete. DELETE /api/v1/plants/:plantId sets plants.deleted_at to the current UTC instant and updated_at to the same value. The row is otherwise untouched — last_watered_on, name, notes, and watering_interval_days are preserved so the 10-second Undo affordance (Section 10) can restore the plant exactly as it was via POST /api/v1/plants/:plantId/restore, which sets deleted_at back to NULL.

• The 30-day purge permanently removes soft-deleted plants and, via the ON DELETE CASCADE foreign key on waterings.plant_id, all of that plant's watering rows in the same statement. The purge task runs once at process start and then on a 24-hour interval, executing:

  Copy

  DELETE FROM plants
  WHERE deleted_at IS NOT NULL
    AND deleted_at <= ?; -- bound parameter: (now - 30 days) as an ISO 8601 UTC instant string

  The cutoff instant is computed in application code (subDays in UTC, not through APP_TIMEZONE — purge timing is an operational concern, not a calendar-date concern, so it uses plain UTC instant arithmetic) and passed as a bound parameter; the query never uses SQLite's own datetime('now', ...) so the cutoff is computed once and is trivially unit-testable. Because deleted_at values are ISO 8601 UTC strings with zero-padded fields, lexicographic string comparison (<=) is equivalent to chronological comparison.

  After the DELETE, the task writes the number of rows affected to the log (Section 22) and updates settings.last_purge_run_at.

• Waterings hard-delete individually. DELETE /api/v1/plants/:plantId/waterings/:wateringId removes exactly that row with no cascade (a watering has no children). Deleting a watering recomputes the parent plant's last_watered_on only when the deleted row's watered_on equals the plant's current last_watered_on; otherwise last_watered_on is left untouched, because a backdating edit may already have moved last_watered_on earlier than MAX(watered_on) on purpose, and deleting an unrelated older row must never silently pull it forward again (the never-advance rule in Section 8.2):

  1. If the deleted row's watered_on is not equal to the plant's current last_watered_on, no recomputation happens; last_watered_on and updated_at are unchanged.
  2. Otherwise, the repository re-queries MAX(watered_on) for the remaining watering rows of that plant. If a maximum exists, plants.last_watered_on is set to it and updated_at is refreshed.
  3. If no watering rows remain (the deleted row was the plant's only watering), last_watered_on is set to the earlier of the calendar date of plants.created_at converted through APP_TIMEZONE (todayInTimeZone-style conversion applied to the stored created_at instant, not to "now") and the plant's current last_watered_on — never a later date, so this fallback can only preserve or increase how overdue the plant is, and never NULL, preserving the Section 8.2 invariant. This is the fallback the domain layer defines in Section 8.2, and it is deterministic: re-running the same deletion against the same data always produces the same last_watered_on. All steps run inside a single SQLite transaction so a crash between them cannot leave last_watered_on pointing at a watering row that no longer exists.

7.9 Derived and non-stored values #

Every one of these values is computed on every read, server-side, using the pure functions in Section 8.4, and returned in the plant DTO alongside the stored fields. The client may recompute them optimistically (Section 8.4, Section 16) but never writes them back.

7.10 Migration files #

0001_init.sql, the first and — as of this specification — only migration, creates every table and index defined in Sections 7.3–7.6:

-- 0001_init.sql
-- Creates the full initial schema: plants, waterings, settings.
-- (schema_migrations itself is created by the migration runner, not by this file — see Section 7.6.)

CREATE TABLE plants (
  id                      TEXT PRIMARY KEY,
  name                    TEXT NOT NULL,
  watering_interval_days  INTEGER NOT NULL,
  notes                   TEXT NULL,
  last_watered_on         TEXT NOT NULL,
  created_at              TEXT NOT NULL,
  updated_at              TEXT NOT NULL,
  deleted_at              TEXT NULL,
  CHECK (watering_interval_days BETWEEN 1 AND 365),
  CHECK (length(trim(name)) BETWEEN 1 AND 60),
  CHECK (notes IS NULL OR length(notes) <= 2000),
  CHECK (last_watered_on GLOB '[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]')
);

CREATE INDEX idx_plants_deleted_at ON plants(deleted_at);
CREATE INDEX idx_plants_last_watered_on ON plants(last_watered_on);

CREATE TABLE waterings (
  id          TEXT PRIMARY KEY,
  plant_id    TEXT NOT NULL REFERENCES plants(id) ON DELETE CASCADE,
  watered_on  TEXT NOT NULL,
  created_at  TEXT NOT NULL,
  CHECK (watered_on GLOB '[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]')
);

CREATE UNIQUE INDEX uq_waterings_plant_date ON waterings(plant_id, watered_on);
CREATE INDEX idx_waterings_plant_id_watered_on_desc ON waterings(plant_id, watered_on DESC);

CREATE TABLE settings (
  key         TEXT PRIMARY KEY,
  value       TEXT NOT NULL,
  updated_at  TEXT NOT NULL
);

Migration runner contract:

• Migration files live in apps/api/migrations/ and are named NNNN_snake_case_name.sql, a four-digit zero-padded integer, an underscore, and a lowercase snake_case description (e.g. 0001_init.sql, 0002_add_plant_index.sql).
• On boot, the runner: (1) ensures schema_migrations exists (Section 7.6); (2) lists migration files sorted by their numeric prefix ascending; (3) recomputes and verifies checksums for every file whose version is already recorded (Section 7.6); (4) for each unrecorded file, in ascending order, reads its contents, opens a single better-sqlite3 transaction (db.transaction(() => { db.exec(sql); db.prepare('INSERT INTO schema_migrations (...) VALUES (...)').run(...); })()), and runs the file's SQL followed by inserting its own schema_migrations row, so the migration's DDL and its ledger entry commit or roll back together.
• A migration file, once applied (its version exists in schema_migrations), must never be edited. Any further schema change is a new file with the next integer.
• No down-migrations exist. The rollback strategy for a bad migration is to restore the most recent backup snapshot (Section 24) and re-deploy the previous application version; forward-only migrations keep the runner and the schema simple, which matches the single-environment, single-writer nature of this product.

7.11 Seed and demo data #

An optional npm run seed --workspace=apps/api command inserts the fixture defined in Section 30.5. Every last_watered_on in that fixture is expressed relative to "today" at seed time rather than as a fixed date, so the resulting status spread is identical regardless of what day the seed command runs.

The seed script computes today once via todayInTimeZone(new Date(), APP_TIMEZONE) (Section 8.4), derives each plant's last_watered_on with addDays(today, -N) per the fixture in Section 30.5 (Section 8.4), inserts each plant row and a single matching waterings row (watered_on equal to the plant's last_watered_on, created_at equal to the current instant), and prints the generated names and computed statuses to stdout for operator confirmation.

Seeding refuses to run against a non-empty database: it first runs SELECT COUNT(*) FROM plants, and if the count is greater than zero, it exits with a non-zero status and the message "Refusing to seed: N existing plant(s) found. Pass --force to seed anyway." unless invoked with --force, in which case it proceeds without deleting existing rows (it only adds the 8 seed rows on top).

7.12 Storage sizing #

Worst-case row size, plants (every optional field at its maximum):

At the hard cap of 500 active plants, worst-case plants data is 500 × 8,366 ≈ 4.1 MB. In practice almost no plant will have a 2000-character notes field, so real-world usage is far smaller.

Worst-case waterings volume, ten years of daily watering for all 500 plants at the cap: 500 plants × 3,653 days (10 years including 2–3 leap days) ≈ 1,826,500 rows. Each row is 36 (id) + 36 (plant_id) + 10 (watered_on) + 24 (created_at) ≈ 106 bytes, giving 1,826,500 × 106 ≈ 193.6 MB of row data. Adding the two waterings indexes (roughly comparable in size to the row data for narrow indexes at this cardinality, a conservative 1.5× multiplier) brings the total database file to on the order of 300–350 MB after ten years at the absolute maximum plant count and maximum realistic watering frequency (once per calendar day is already the practical ceiling, since the unique index in Section 7.4 forbids more than one watering row per plant per day).

This comfortably fits in memory and on any reasonable persistent volume for the lifetime of the product; no archival, partitioning, or data-tiering strategy is warranted, and none is specified anywhere in this document.

7.13 Repository layer contract #

Repositories are the only place raw SQL exists in the codebase. Every statement is a prepared statement created once (module scope) and reused with bound parameters — no string-built or concatenated SQL anywhere, for both correctness and injection safety (cross-reference Section 20). Repositories map snake_case rows to camelCase DTOs (Section 3); no other layer touches better-sqlite3 directly.

// apps/api/src/db/repositories/plant-repository.ts

export interface PlantRow {
  id: string;
  name: string;
  watering_interval_days: number;
  notes: string | null;
  last_watered_on: string;
  created_at: string;
  updated_at: string;
  deleted_at: string | null;
}

export interface CreatePlantInput {
  id: string;
  name: string;
  wateringIntervalDays: number;
  notes: string | null;
  lastWateredOn: string;
  now: string; // ISO 8601 UTC instant, used for created_at and updated_at
}

export interface UpdatePlantInput {
  name?: string;
  wateringIntervalDays?: number;
  notes?: string | null;
  now: string;
}

export interface PlantRepository {
  /** Non-deleted plants, ordered by created_at ascending. Maps every row to a PlantRow. */
  findAll(): PlantRow[];

  /** A single plant by id, including soft-deleted ones (callers filter on deleted_at as needed). */
  findById(id: string): PlantRow | null;

  /** COUNT(*) of active (deleted_at IS NULL) plants, for the 500-plant cap check (Section 9.5). */
  countActive(): number;

  /** Inserts a new plant row. created_at and updated_at are both set to input.now. */
  create(input: CreatePlantInput): PlantRow;

  /** Partial update of name / wateringIntervalDays / notes. Always refreshes updated_at. Returns
   *  null if no active plant with that id exists. */
  update(id: string, input: UpdatePlantInput): PlantRow | null;

  /** Sets deleted_at = now. Returns false if the plant does not exist or is already deleted. */
  softDelete(id: string, now: string): boolean;

  /** Clears deleted_at. Returns the restored row, or null if the plant does not exist or was not
   *  deleted. */
  restore(id: string, now: string): PlantRow | null;

  /** Directly sets last_watered_on and updated_at, used by the watering-recompute path in
   *  Section 7.8 and by the "Watered today" action in Section 11. */
  updateLastWateredOn(id: string, lastWateredOn: string, now: string): void;

  /** Hard-deletes every plant with deleted_at <= cutoffInstant (Section 7.8). Returns the number of
   *  rows deleted. Cascades to waterings via the foreign key. */
  purgeDeletedBefore(cutoffInstant: string): number;
}

// apps/api/src/db/repositories/watering-repository.ts

export interface WateringRow {
  id: string;
  plant_id: string;
  watered_on: string;
  created_at: string;
}

export interface CreateWateringInput {
  id: string;
  plantId: string;
  wateredOn: string;
  now: string;
}

export interface WateringPage {
  rows: WateringRow[];
  total: number;
}

export type CreateWateringResult =
  | { created: true; row: WateringRow }
  | { created: false; row: WateringRow }; // row already existed for that plant + date (idempotent path)

export interface WateringRepository {
  /** Paginated history for one plant, newest first, using idx_waterings_plant_id_watered_on_desc. */
  findByPlantId(plantId: string, limit: number, offset: number): WateringPage;

  /** The single most recent watering row for a plant, or null if it has none (should not normally
   *  happen given Section 8.2, but the type models the possibility explicitly). */
  findLatestForPlant(plantId: string): WateringRow | null;

  /** Attempts to insert; if uq_waterings_plant_date rejects the insert (SQLITE_CONSTRAINT_UNIQUE),
   *  catches it, re-reads the existing row for (plantId, wateredOn), and returns { created: false,
   *  row }. Never throws for the duplicate case. */
  create(input: CreateWateringInput): CreateWateringResult;

  /** Deletes a single watering row by id (and, by contract, only if it belongs to plantId — callers
   *  pass both so a mismatched id/plantId pair returns null rather than deleting the wrong plant's
   *  row). Returns the deleted row (so the caller can recompute plants.last_watered_on per Section
   *  7.8) or null if no matching row existed. */
  deleteById(plantId: string, wateringId: string): WateringRow | null;

  /** COUNT(*) of waterings for a plant, used for the wateringCount derived value (Section 7.9). */
  countForPlant(plantId: string): number;
}

8. Watering Schedule Domain Logic #

8.1 Vocabulary #

8.2 The invariant #

lastWateredOn is never null for any plant that exists in the system. Every code path that can create or mutate a plant row must uphold this:

If a row is ever found to violate the invariant (for example, a hand-edited database file, or a future migration bug), the read path never crashes. computeScheduleView (Section 8.4) is never called with a null lastWateredOn in the first place, because the repository layer guards it: on read, if plants.last_watered_on is NULL or fails the calendar-date GLOB/validity check, the API (1) logs an ERROR-level structured log line including the plant id and the raw stored value (Section 22), (2) treats the plant's created_at instant, converted to a calendar date via APP_TIMEZONE, as the repaired value for that response only, and (3) adds the plant's id to meta.repairedPlantIds: string[] on the list and detail responses so the client can surface a non-blocking "this plant's data was repaired" notice for each affected plant. The repository does not write the repaired value back automatically — a background repair would silently mutate data the operator might want to investigate first; the actual row is only corrected if a subsequent legitimate mutation (an edit or a watering) touches it.

8.3 The four statuses #

Boundary examples, holding today = 2026-08-05:

These four values, spelled exactly as shown (overdue, due_today, due_soon, upcoming), are the only legal values of the status field anywhere in the API or the database layer; no other string is ever produced or accepted.

8.4 Function specifications #

All functions in this section live in packages/shared/src/domain/schedule.ts and packages/shared/src/domain/calendar-date.ts, are pure (no I/O, no Date.now() calls except where a now/today value is an explicit parameter), total (they never throw for inputs that satisfy their documented parameter contract), and dependency-light: calendar-date arithmetic (addDays, differenceInCalendarDays, and the calendar-date validity check reused by Section 9.4) is implemented with plain integer arithmetic and never constructs a JavaScript Date object, so its correctness can never depend on the host process's local timezone setting. The only function that crosses the instant-to-calendar-date boundary, todayInTimeZone, uses @date-fns/tz and date-fns exactly once, precisely because that conversion is the one place an IANA timezone genuinely has to be consulted.

// packages/shared/src/domain/calendar-date.ts

export type CalendarDate = string & { readonly __brand: 'CalendarDate' };

const DAYS_IN_MONTH = [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];

function isLeapYear(year: number): boolean {
  return (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0;
}

function daysInMonth(year: number, month: number): number {
  // month is 1-12
  if (month === 2 && isLeapYear(year)) return 29;
  return DAYS_IN_MONTH[month - 1] ?? 31;
}

/** True if year/month/day form a real proleptic-Gregorian calendar date. */
export function isValidCalendarDateParts(year: number, month: number, day: number): boolean {
  if (!Number.isInteger(year) || !Number.isInteger(month) || !Number.isInteger(day)) return false;
  if (month < 1 || month > 12) return false;
  if (day < 1 || day > daysInMonth(year, month)) return false;
  return true;
}

const CALENDAR_DATE_SHAPE = /^(\d{4})-(\d{2})-(\d{2})$/;

/** True if the string is both YYYY-MM-DD shaped and a real calendar date. */
export function isValidCalendarDate(value: string): value is CalendarDate {
  const match = CALENDAR_DATE_SHAPE.exec(value);
  if (!match) return false;
  const y = Number(match[1]);
  const m = Number(match[2]);
  const d = Number(match[3]);
  return isValidCalendarDateParts(y, m, d);
}

function parseCalendarDate(date: CalendarDate): { year: number; month: number; day: number } {
  const parts = date.split('-');
  const year = Number(parts[0]);
  const month = Number(parts[1]);
  const day = Number(parts[2]);
  return { year, month, day };
}

function formatCalendarDate(year: number, month: number, day: number): CalendarDate {
  const yy = String(year).padStart(4, '0');
  const mm = String(month).padStart(2, '0');
  const dd = String(day).padStart(2, '0');
  return `${yy}-${mm}-${dd}` as CalendarDate;
}

// Howard Hinnant's civil_from_days / days_from_civil algorithm: an exact, branch-light conversion
// between a proleptic-Gregorian (year, month, day) and a day count relative to 1970-01-01, correct
// for every year including leap years and leap days, with no floating-point rounding risk in the
// ranges this product uses (1970-01-01 through 2400-12-31 and beyond).
function daysFromCivil(year: number, month: number, day: number): number {
  const y = month <= 2 ? year - 1 : year;
  const era = Math.floor((y >= 0 ? y : y - 399) / 400);
  const yoe = y - era * 400; // [0, 399]
  const doy = Math.floor((153 * (month + (month > 2 ? -3 : 9)) + 2) / 5) + day - 1; // [0, 365]
  const doe = yoe * 365 + Math.floor(yoe / 4) - Math.floor(yoe / 100) + doy; // [0, 146096]
  return era * 146097 + doe - 719468; // days relative to 1970-01-01
}

function civilFromDays(daysSinceEpoch: number): { year: number; month: number; day: number } {
  const z = daysSinceEpoch + 719468;
  const era = Math.floor((z >= 0 ? z : z - 146096) / 146097);
  const doe = z - era * 146097; // [0, 146096]
  const yoe = Math.floor(
    (doe - Math.floor(doe / 1460) + Math.floor(doe / 36524) - Math.floor(doe / 146096)) / 365
  ); // [0, 399]
  const y = yoe + era * 400;
  const doy = doe - (365 * yoe + Math.floor(yoe / 4) - Math.floor(yoe / 100)); // [0, 365]
  const mp = Math.floor((5 * doy + 2) / 153); // [0, 11]
  const day = doy - Math.floor((153 * mp + 2) / 5) + 1; // [1, 31]
  const month = mp + (mp < 10 ? 3 : -9); // [1, 12]
  const year = y + (month <= 2 ? 1 : 0);
  return { year, month, day };
}

/** Adds (or subtracts, for negative `days`) whole calendar days to a calendar date. Pure integer
 *  arithmetic; never touches a JS Date object. */
export function addDays(date: CalendarDate, days: number): CalendarDate {
  const { year, month, day } = parseCalendarDate(date);
  const epochDay = daysFromCivil(year, month, day) + days;
  const result = civilFromDays(epochDay);
  return formatCalendarDate(result.year, result.month, result.day);
}

/** Number of calendar days from `b` to `a` (positive when `a` is after `b`). */
export function differenceInCalendarDays(a: CalendarDate, b: CalendarDate): number {
  const pa = parseCalendarDate(a);
  const pb = parseCalendarDate(b);
  return daysFromCivil(pa.year, pa.month, pa.day) - daysFromCivil(pb.year, pb.month, pb.day);
}

// packages/shared/src/domain/schedule.ts
import { TZDate } from '@date-fns/tz';
import { format } from 'date-fns';
import {
  type CalendarDate,
  addDays,
  differenceInCalendarDays,
} from './calendar-date';

export type PlantStatus = 'overdue' | 'due_today' | 'due_soon' | 'upcoming';

export interface ScheduleView {
  nextDueOn: CalendarDate;
  daysUntilDue: number;
  daysOverdue: number;
  status: PlantStatus;
}

export interface SchedulePlantInput {
  lastWateredOn: CalendarDate;
  wateringIntervalDays: number;
}

/** Converts an instant into "today" in the given IANA timezone. The only function in this module
 *  that consults a timezone. */
export function todayInTimeZone(now: Date, timeZone: string): CalendarDate {
  const zoned = new TZDate(now.getTime(), timeZone);
  return format(zoned, 'yyyy-MM-dd') as CalendarDate;
}

/** nextDueOn = lastWateredOn + wateringIntervalDays, pure calendar arithmetic, no DST adjustment. */
export function computeNextDueOn(
  lastWateredOn: CalendarDate,
  wateringIntervalDays: number
): CalendarDate {
  return addDays(lastWateredOn, wateringIntervalDays);
}

/** Maps a computed daysUntilDue to one of the four canonical statuses (Section 8.3). */
function statusFromDaysUntilDue(daysUntilDue: number): PlantStatus {
  if (daysUntilDue < 0) return 'overdue';
  if (daysUntilDue === 0) return 'due_today';
  if (daysUntilDue === 1) return 'due_soon';
  return 'upcoming';
}

/** Status only, given nextDueOn and today. */
export function computeStatus(nextDueOn: CalendarDate, today: CalendarDate): PlantStatus {
  return statusFromDaysUntilDue(differenceInCalendarDays(nextDueOn, today));
}

/** True if a plant with this lastWateredOn has already been watered today. Used by the idempotency
 *  check in Section 11.2. */
export function isAlreadyWateredToday(lastWateredOn: CalendarDate, today: CalendarDate): boolean {
  return lastWateredOn === today;
}

/** The full derived view for one plant on one day: everything Section 7.9 says must never be
 *  stored. */
export function computeScheduleView(plant: SchedulePlantInput, today: CalendarDate): ScheduleView {
  const nextDueOn = computeNextDueOn(plant.lastWateredOn, plant.wateringIntervalDays);
  const daysUntilDue = differenceInCalendarDays(nextDueOn, today);
  const status = statusFromDaysUntilDue(daysUntilDue);
  const daysOverdue = status === 'overdue' ? -daysUntilDue : 0;
  return { nextDueOn, daysUntilDue, daysOverdue, status };
}

/** The exact, and only, user-facing phrasing for a plant's due state. No other phrasing is
 *  permitted anywhere in the UI (Section 17). */
export function formatRelativeDueLabel(daysUntilDue: number): string {
  if (daysUntilDue < 0) {
    const n = -daysUntilDue;
    return n === 1 ? 'Overdue by 1 day' : `Overdue by ${n} days`;
  }
  if (daysUntilDue === 0) return 'Due today';
  if (daysUntilDue === 1) return 'Due tomorrow';
  return `Due in ${daysUntilDue} days`;
}

const STATUS_URGENCY_RANK: Record<PlantStatus, number> = {
  overdue: 0,
  due_today: 1,
  due_soon: 2,
  upcoming: 3,
};

/** Canonical sort comparator: most urgent first. Within `overdue`, the most-overdue plant sorts
 *  first. Within `upcoming`, the soonest-due plant sorts first. Ties break on name
 *  (case-insensitive, locale-pinned), then on `id`, so the order is a total order and never
 *  depends on the host process's locale. */
export function compareByUrgency(
  a: { status: PlantStatus; daysUntilDue: number; name: string; id: string },
  b: { status: PlantStatus; daysUntilDue: number; name: string; id: string }
): number {
  const rankDiff = STATUS_URGENCY_RANK[a.status] - STATUS_URGENCY_RANK[b.status];
  if (rankDiff !== 0) return rankDiff;
  if (a.status === 'overdue') {
    if (a.daysUntilDue !== b.daysUntilDue) return b.daysUntilDue - a.daysUntilDue; // more negative = more overdue = first
  } else if (a.daysUntilDue !== b.daysUntilDue) {
    return a.daysUntilDue - b.daysUntilDue;
  }
  const nameDiff = a.name.localeCompare(b.name, 'en', { sensitivity: 'base' });
  if (nameDiff !== 0) return nameDiff;
  return a.id.localeCompare(b.id);
}

Worked examples, todayInTimeZone (APP_TIMEZONE = America/New_York, offset UTC−5 outside DST):

Worked examples, addDays:

Worked examples, differenceInCalendarDays:

Worked examples, computeStatus / computeScheduleView (lastWateredOn = 2026-08-01, wateringIntervalDays = 7, so nextDueOn = 2026-08-08):

Worked examples, formatRelativeDueLabel:

Pluralisation rule: "day" is singular only for exactly 1 day overdue ("Overdue by 1 day"); every other overdue count and every upcoming count uses "days" (there is no singular upcoming case because upcoming never applies to daysUntilDue === 1, which is always due_soon). No other phrasing — no "Xd overdue", no "in X days!", no localisation variants — is permitted anywhere in the UI; every screen that shows a due label (Section 17) calls this function.

Worked example, compareByUrgency, sorting four plants (today = 2026-08-05):

Within overdue, the comparator returns b.daysUntilDue - a.daysUntilDue, so a plant with daysUntilDue = -5 (Fiddle Leaf Fig) sorts before one with daysUntilDue = -1 (Snake Plant), because -1 - (-5) = 4 > 0. The final order is: Fiddle Leaf Fig (−5, most overdue), Snake Plant (−1), Pothos (due_today), Monstera (upcoming).

8.5 Timezone and DST correctness #

Calendar arithmetic in this system is deliberately performed on YYYY-MM-DD values using the integer day-count algorithm in Section 8.4, never on millisecond instants shifted by a fixed offset. Millisecond arithmetic on a Date object is unsafe for this domain for two independent reasons: (1) adding "24 hours" to an instant does not reliably land on the same wall-clock time the next day across a Daylight Saving Time transition (the local day can be 23 or 25 hours long), and (2) any arithmetic performed with a JS Date's local getters (getDate(), getMonth(), etc.) silently depends on the host process's TZ environment variable rather than on APP_TIMEZONE, which is a configuration value, not a process environment property. addDays and differenceInCalendarDays sidestep both problems by never constructing a Date at all (Section 8.4); the only place an instant is ever converted into a calendar date is todayInTimeZone, which explicitly takes APP_TIMEZONE as a parameter and uses @date-fns/tz to perform that one conversion correctly.

The following six scenarios each demonstrate a different timezone hazard and confirm the system produces the correct result:

Row-by-row notes:

1. 2026-03-08 is the second Sunday of March 2026, when America/New_York springs forward at 2 a.m. local. At the sampled UTC instant, local time is 01:30 EST (still UTC−5, just before the jump). today is unaffected by the fact that the local day will be one hour short later that day, because today is a calendar date, not a duration.
2. 2026-11-01 is the first Sunday of November 2026, when America/New_York falls back at 2 a.m. local (EDT UTC−4 → EST UTC−5). At the sampled instant, local time is 04:30 EST, after the transition. Despite the local day being 25 hours long, nextDueOn and daysUntilDue are computed from calendar dates alone and are exactly what plain calendar subtraction gives: 5 days overdue.
3. Pacific/Auckland observes NZDT (UTC+13) in January (southern-hemisphere summer). The sampled UTC instant 20:00 on the 15th is 09:00 on the 16th locally — a full calendar day ahead of the UTC date. This is precisely why todayInTimeZone must convert through APP_TIMEZONE and never simply take the UTC date's YYYY-MM-DD substring.
4. Pacific/Pago_Pago is UTC−11 year-round (no DST observed). The sampled instant 08:00 on the 16th is 21:00 on the 15th locally — a full calendar day behind the UTC date, the mirror-image hazard of row 3.
5. Asia/Kolkata is UTC+5:30 year-round. The half-hour offset does not participate in the calendar-date calculation at all once todayInTimeZone has produced the YYYY-MM-DD string; everything downstream is pure integer day arithmetic, so a fractional-hour offset introduces no special case anywhere in Section 8.4.
6. 2028 is a leap year (2028 / 4 = 507 exactly, and 2028 is not a century year), so February has 29 days. addDays(2028-02-15, 14) must land on 2028-02-29, not roll over into March; the Section 8.4 algorithm handles this automatically because daysInMonth and the Hinnant conversion both encode the leap-year rule directly, with no special-cased "if leap year" branch anywhere in addDays itself.

Invalid APP_TIMEZONE values. APP_TIMEZONE is validated once, at process boot, against the IANA Time Zone Database via Intl.supportedValuesOf('timeZone') (or, if unavailable in the runtime, by attempting new Intl.DateTimeFormat('en-US', { timeZone: value }) and catching the RangeError it throws for an unknown zone). An invalid value fails configuration validation and the process exits with code 78 before opening a database connection or binding a port (Section 21). There is no runtime fallback to UTC for an invalid value — an operator typo is a configuration error to be fixed, not silently masked.

8.6 Day-rollover behaviour #

At local midnight in APP_TIMEZONE, today (Section 8.1) advances by one calendar day. This changes, for every plant, exactly these derived values: daysUntilDue, daysOverdue, and status (and, by extension, formatRelativeDueLabel's output and compareByUrgency's ordering). It changes nothing that is stored: plants.last_watered_on is untouched, no row is written, no migration or scheduled SQL statement runs at midnight.

The server holds no timer, cron job, or scheduled task tied to midnight for status purposes — every status value is computed fresh on every read, from lastWateredOn and wateringIntervalDays against whatever today is at the moment of the request (Section 8.4). This means a request made one second after local midnight in APP_TIMEZONE already sees the new day's statuses with zero propagation delay, and a request made one second before sees the previous day's statuses; there is no in-between state to reconcile.

Because the server is stateless with respect to time, it is the client's responsibility to notice when a new calendar day has begun while a tab is left open, since nothing pushes an update to it. The client schedules a timer for the next local-midnight boundary in APP_TIMEZONE (using the timezone returned in meta.timezone, Section 8.4) and re-fetches the plant list when it fires, rescheduling for the following midnight afterward — this refresh trigger and its surrounding cache policy are canonical in Section 16.

8.7 Clock-change and clock-skew handling #

• Host clock jumps backwards (e.g. an NTP correction, a container restart with a skewed hardware clock). The server does not track "last seen time" for schedule purposes, so a backward jump has no special-case handling: the very next request simply computes today from whatever instant new Date() returns at that moment (Section 8.1's todayInTimeZone(new Date(), APP_TIMEZONE)). If the jump is large enough to change the calendar date, statuses reflect the corrected date immediately and consistently on the next request; nothing needs to be un-done because nothing was written based on the skewed time (Section 7.9 — no derived value is ever persisted).
• Operator changes APP_TIMEZONE between restarts. This is an expected, supported operation, not an error condition. Every plant's nextDueOn/daysUntilDue/status is recomputed from the same stored lastWateredOn and wateringIntervalDays against a today calculated in the new timezone, which can shift every plant's apparent due-ness by up to one calendar day in either direction (identical in kind to the divergence shown in Section 8.5, rows 3–4). This is correct and intended behaviour, and it is documented for operators in Section 21 rather than treated as a bug.
• Client clock disagrees with server clock. The client may recompute nextDueOn/daysUntilDue/ status optimistically using the shared pure functions (Section 8.4, Section 16), but the client's own device clock and timezone are never authoritative for anything persisted or returned by a subsequent request: the server's computed value, using the server process's clock and the configured APP_TIMEZONE, always wins the moment the client's next fetch completes. A client with a fast, slow, or wrongly-zoned system clock can only ever cause a brief, self-correcting visual discrepancy between refreshes — never a data-integrity issue, since the client never writes a computed value back to the server.

8.8 Worked end-to-end examples #

Each scenario traces one plant through a sequence of events. All dates assume APP_TIMEZONE = UTC for simplicity; the arithmetic is identical in any timezone once today has been established (Section 8.5).

Scenario 1 — ordinary cycle, watered on time.

Scenario 2 — watered late, interval unchanged.

Scenario 3 — idempotent same-day watering.

Scenario 4 — shortening the interval makes a plant instantly overdue.

The edit in step 3 is applied exactly as specified: nextDueOn is recomputed from the unchanged lastWateredOn, producing an immediate overdue status. This is correct and intended; nothing clamps the result.

Scenario 5 — lengthening the interval defers the next due date.

Scenario 6 — deleting the only watering entry resets lastWateredOn to created_at's date.

Scenario 7 — deleting a non-latest watering entry recomputes to the remaining latest.

Scenario 8 — watering while overdue clears the overdue state entirely, never partially.

There is no partial credit for lateness: watering resets lastWateredOn to today regardless of how many days overdue the plant was, and daysOverdue returns to 0 in the very next read.

Scenario 9 — daily interval (wateringIntervalDays = 1) is always due_soon the instant after watering, never upcoming.

Scenario 10 — maximum interval (wateringIntervalDays = 365) spanning a leap day.

8.9 Property-based invariants #

The following hold for every valid input (1 <= wateringIntervalDays <= 365, lastWateredOn and today any real calendar dates) and are the basis for the property-based tests named in Section 25:

1. lastWateredOn is never null for any plant returned by the API (Section 8.2).
2. computeStatus always returns exactly one of the four enum values — never undefined, never a fifth value — for any nextDueOn/today pair, because the four conditions in Section 8.3 (< 0, === 0, === 1, >= 2) are exhaustive and mutually exclusive over the integers.
3. Watering a plant never immediately produces overdue or due_today. Because wateringIntervalDays >= 1 always (interval 0 is not a valid input — the real minimum is 1, Section 9.3), nextDueOn = addDays(today, wateringIntervalDays) >= addDays(today, 1), so daysUntilDue >= 1 immediately after watering: the result is due_soon when wateringIntervalDays === 1 and upcoming when wateringIntervalDays >= 2.
4. nextDueOn is a function of lastWateredOn and wateringIntervalDays alone. It never changes when only today changes; only daysUntilDue, daysOverdue, and status vary with today.
5. Status urgency is non-decreasing as today advances, holding nextDueOn fixed: moving today forward by any positive number of days can only move status along upcoming → due_soon → due_today → overdue, never backward, and only a watering event (which changes lastWateredOn and therefore nextDueOn) can reduce urgency.
6. addDays and differenceInCalendarDays are inverses: differenceInCalendarDays(addDays(d, n), d) === n for every integer n (positive, negative, or zero) and every valid calendar date d, including across month, year, and leap-day boundaries.
7. daysOverdue is exactly 0 when status !== 'overdue', and exactly -daysUntilDue (a positive integer) when status === 'overdue'. There is no state in which daysOverdue is positive while status is not overdue, or vice versa.
8. The schedule functions are pure and total: two calls to computeScheduleView with identical lastWateredOn, wateringIntervalDays, and today arguments always return bitwise-identical results, with no dependency on call order, wall-clock time at the moment of the call, or any mutable state — editing wateringIntervalDays alone (Scenario 4/5 in Section 8.8) always recomputes nextDueOn deterministically from the stored lastWateredOn.

9. Validation Rules and Limits #

9.1 Validation philosophy #

Every validation rule in this product is expressed exactly once, as a Zod schema in packages/shared/src/schemas/, and imported by both apps/api and apps/web (Section 5.1). There are three layers, in order of authority:

1. Client-side validation (the same Zod schemas, run in the browser before a request is sent) exists purely for fast user feedback — a form can show an inline error before a network round trip. It is never trusted as the source of truth.
2. Server-side validation (the same Zod schemas, run in a Fastify preValidation hook on every route, Section 13) is the authority. Every request is validated here regardless of what the client already checked, because the client is not trusted.
3. Database CHECK constraints (Section 7.3, Section 7.4) are the last-resort backstop against a bug that bypasses the application layer entirely. They are deliberately looser than the Zod schemas (Section 7.3) and are never relied upon to produce a user-facing error message.

No validation rule is ever encoded in only one of these layers when it could reasonably be encoded in more than one; the field-limit rules in Section 9.3 exist in both the Zod schema and, for the fields that have one, a database CHECK constraint.

9.2 Normalisation pipeline #

Input strings are normalised in a fixed order before the length and content checks in Section 9.3 are applied, so that, for example, a name that is only valid after trimming is correctly accepted, and a name that is too long only after Unicode normalisation is correctly rejected. The order is:

1. Unicode NFC normalisation — canonical composition, so that visually identical strings (e.g. an "é" typed as a single code point versus as "e" + combining acute accent) compare and store identically.
2. Control-character stripping — every C0 (U+0000–U+001F) and C1 (U+007F–U+009F) control character is removed from name with no exceptions (this means no newlines, tabs, or carriage returns are ever allowed in name). For notes, every C0/C1 control character is removed except line feed (U+000A) and carriage return (U+000D), which are preserved because notes is free text that may reasonably span multiple lines. name additionally strips every zero-width and bidirectional-formatting character (soft hyphen, zero-width space/joiner/non-joiner, the left-to-right/right-to-left embedding and override marks, word joiner, invisible math operators, and the byte-order mark) so a name cannot render as blank or visually reverse adjacent UI text while still passing the length check below; after this step a name must contain at least one remaining non-whitespace character or it fails validation (Section 9.3).
3. Whitespace collapsing — applied to name only: any run of one or more Unicode whitespace characters is collapsed to a single ASCII space. Not applied to notes, which preserves its internal formatting (including blank lines) as the user typed it.
4. Trimming — leading and trailing whitespace is removed from both name and notes.
5. Empty-to-null — applied to notes only: if the string is empty after the previous four steps, it becomes null rather than an empty string. name has no equivalent step because an empty name is always a validation failure (Section 9.3), never a stored empty value.

// packages/shared/src/schemas/normalize.ts

const CONTROL_CHARS_ALL = /[\u0000-\u001F\u007F-\u009F]/g;
const CONTROL_CHARS_EXCEPT_NEWLINES = /[\u0000-\u0009\u000B\u000C\u000E-\u001F\u007F-\u009F]/g;
const INVISIBLE_FORMATTING_CHARS = /[\u00AD\u200B-\u200F\u202A-\u202E\u2060-\u2064\u2066-\u2069\uFEFF]/g;
const WHITESPACE_RUN = /\s+/g;

export function normalizeName(input: string): string {
  return input
    .normalize('NFC')
    .replace(CONTROL_CHARS_ALL, '')
    .replace(INVISIBLE_FORMATTING_CHARS, '')
    .replace(WHITESPACE_RUN, ' ')
    .trim();
}

export function normalizeNotes(input: string | undefined | null): string | null {
  if (input === undefined || input === null) return null;
  const cleaned = input
    .normalize('NFC')
    .replace(CONTROL_CHARS_EXCEPT_NEWLINES, '')
    .trim();
  return cleaned === '' ? null : cleaned;
}

Both functions run as Zod .transform() steps (Section 9.4), so the value a route handler receives has already passed through this pipeline; no route ever normalises input itself.

9.3 Field rules table #

9.4 The Zod schemas #

// packages/shared/src/schemas/calendar-date.ts
import { z } from 'zod';
import { isValidCalendarDate, type CalendarDate } from '../domain/calendar-date';

export const CALENDAR_DATE_SHAPE = /^\d{4}-\d{2}-\d{2}$/;

const DATE_MESSAGE =
  'Date must be a real calendar date in YYYY-MM-DD form, not in the future, and not before 1970-01-01.';

export const CalendarDateSchema = z
  .string()
  .regex(CALENDAR_DATE_SHAPE, DATE_MESSAGE)
  .refine(isValidCalendarDate, DATE_MESSAGE)
  .transform((value) => value as CalendarDate);

export type CalendarDateInput = z.infer<typeof CalendarDateSchema>;

// packages/shared/src/schemas/plant-id.ts
import { z } from 'zod';

const UUID_LOWERCASE_HYPHENATED =
  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;

export const PlantIdSchema = z
  .string()
  .regex(UUID_LOWERCASE_HYPHENATED, 'Must be a valid plant ID.');

export type PlantId = z.infer<typeof PlantIdSchema>;

// packages/shared/src/schemas/plant.ts
import { z } from 'zod';
import { CalendarDateSchema } from './calendar-date';
import { normalizeName, normalizeNotes } from './normalize';
import type { CalendarDate } from '../domain/calendar-date';

const NAME_MESSAGE = 'Name must be between 1 and 60 characters.';

export const NameSchema = z
  .string()
  .transform(normalizeName)
  .pipe(z.string().min(1, NAME_MESSAGE))
  .refine((v) => [...v].length <= 60, NAME_MESSAGE); // length in Unicode code points, not UTF-16 code units

const INTERVAL_MESSAGE = 'Watering interval must be a whole number of days between 1 and 365.';

export const WateringIntervalDaysSchema = z
  .number({ required_error: INTERVAL_MESSAGE, invalid_type_error: INTERVAL_MESSAGE })
  .int(INTERVAL_MESSAGE)
  .min(1, INTERVAL_MESSAGE)
  .max(365, INTERVAL_MESSAGE);

// Distinguishes "absent" (leave unchanged on PATCH) from "explicitly null" (clear it) — see
// Section 9.5's note on the empty-body check, which used to rely on this distinction being lost.
export const NotesSchema = z
  .union([z.string(), z.null()])
  .optional()
  .transform((v) => (v === undefined ? undefined : normalizeNotes(v)))
  .pipe(z.string().max(2000, 'Notes must be 2000 characters or fewer.').nullable().optional());

// Base schema: structural rules only. The today-aware "not in the future" rule for
// lastWateredOn is added by the factory in Section 9.5, because it needs a `today` value that
// only the route handler can supply.
export const CreatePlantBaseSchema = z.object({
  name: NameSchema,
  wateringIntervalDays: WateringIntervalDaysSchema,
  // Create has no "leave unchanged" case, so absent and explicit null both collapse to null.
  notes: NotesSchema.transform((v) => v ?? null),
  lastWateredOn: CalendarDateSchema.optional(),
});

export type CreatePlantInput = z.infer<typeof CreatePlantBaseSchema>;

// No `.refine()` here for "at least one field must be provided" — that check has moved out of Zod
// entirely and runs in the route before this schema is invoked (Section 9.5, Section 10.5).
export const UpdatePlantBaseSchema = z.object({
  name: NameSchema.optional(),
  wateringIntervalDays: WateringIntervalDaysSchema.optional(),
  notes: NotesSchema,
  lastWateredOn: CalendarDateSchema.optional(),
});

export type UpdatePlantInput = z.infer<typeof UpdatePlantBaseSchema>;

// packages/shared/src/schemas/watering.ts
import { z } from 'zod';

const LIMIT_MESSAGE = 'limit must be between 1 and 100.';
const OFFSET_MESSAGE = 'offset must be 0 or greater.';

export const WateringHistoryQuerySchema = z.object({
  limit: z.coerce
    .number({ invalid_type_error: LIMIT_MESSAGE })
    .int(LIMIT_MESSAGE)
    .min(1, LIMIT_MESSAGE)
    .max(100, LIMIT_MESSAGE)
    .default(20),
  offset: z.coerce
    .number({ invalid_type_error: OFFSET_MESSAGE })
    .int(OFFSET_MESSAGE)
    .min(0, OFFSET_MESSAGE)
    .default(0),
});

export type WateringHistoryQuery = z.infer<typeof WateringHistoryQuerySchema>;

// packages/shared/src/schemas/import.ts
// Field-level validation gate for the import payload. The full file format, versioning, and
// import/export behaviour are canonical in Section 24; this schema only enforces per-field shape.
import { z } from 'zod';
import { CalendarDateSchema } from './calendar-date';
import { NameSchema, WateringIntervalDaysSchema, NotesSchema } from './plant';
import { PlantIdSchema } from './plant-id';

const ImportInstantSchema = z
  .string()
  .datetime({ precision: 3, offset: false, message: 'Must be an ISO 8601 UTC instant with milliseconds.' });

export const ImportPlantSchema = z.object({
  id: PlantIdSchema,
  name: NameSchema,
  wateringIntervalDays: WateringIntervalDaysSchema,
  notes: NotesSchema.transform((v) => v ?? null), // an imported row always has notes as string|null, never absent
  lastWateredOn: CalendarDateSchema,
  createdAt: ImportInstantSchema,
  updatedAt: ImportInstantSchema,
  deletedAt: ImportInstantSchema.nullable(),
});

export const ImportWateringSchema = z.object({
  id: PlantIdSchema, // watering ids share the same UUIDv7 shape as plant ids
  plantId: PlantIdSchema,
  wateredOn: CalendarDateSchema,
  createdAt: ImportInstantSchema,
});

// `mode` is supplied by the caller alongside the exported document (Section 24.5); it is never part
// of an export document and this schema validates the combined import *request*, not a raw export.
export const ImportPayloadSchema = z
  .object({
    formatVersion: z.literal(1),
    exportedAt: ImportInstantSchema,
    timezone: z.string().min(1),
    mode: z.enum(['replace', 'merge']),
    plants: z.array(ImportPlantSchema),
    waterings: z.array(ImportWateringSchema),
  })
  .superRefine((value, ctx) => {
    const plantIds = new Set<string>();
    value.plants.forEach((plant, i) => {
      if (plantIds.has(plant.id)) {
        ctx.addIssue({
          code: z.ZodIssueCode.custom,
          path: ['plants', i, 'id'],
          message: 'Duplicate id within the import file.',
        });
      }
      plantIds.add(plant.id);
    });
    const wateringIds = new Set<string>();
    value.waterings.forEach((watering, i) => {
      if (wateringIds.has(watering.id)) {
        ctx.addIssue({
          code: z.ZodIssueCode.custom,
          path: ['waterings', i, 'id'],
          message: 'Duplicate id within the import file.',
        });
      }
      wateringIds.add(watering.id);
      if (!plantIds.has(watering.plantId)) {
        ctx.addIssue({
          code: z.ZodIssueCode.custom,
          path: ['waterings', i, 'plantId'],
          message: 'plantId does not match any plant in the import file.',
        });
      }
    });
  });

export type ImportPayload = z.infer<typeof ImportPayloadSchema>;

9.5 Cross-field and stateful rules #

lastWateredOn must not be in the future relative to today in APP_TIMEZONE. Because "today" depends on the current instant and the configured timezone — neither of which a static schema object can know — the not-in-the-future rule and the not-before-1970-01-01 rule are added by a factory function that takes today as a parameter and is called once per request, immediately after the request's today has been computed:

// packages/shared/src/schemas/plant.ts (continued)
import { differenceInCalendarDays, type CalendarDate } from '../domain/calendar-date';

export const MIN_CALENDAR_DATE = '1970-01-01' as CalendarDate;

function lastWateredOnNotInFuture(today: CalendarDate) {
  return (date: CalendarDate, ctx: z.RefinementCtx) => {
    if (differenceInCalendarDays(date, today) > 0) {
      ctx.addIssue({
        code: z.ZodIssueCode.custom,
        message: 'Date must not be in the future.',
      });
    }
    if (differenceInCalendarDays(date, MIN_CALENDAR_DATE) < 0) {
      ctx.addIssue({
        code: z.ZodIssueCode.custom,
        message: 'Date must not be earlier than 1970-01-01.',
      });
    }
  };
}

export function buildCreatePlantSchema(today: CalendarDate) {
  return CreatePlantBaseSchema.extend({
    lastWateredOn: CalendarDateSchema.optional().superRefine((date, ctx) => {
      if (date !== undefined) lastWateredOnNotInFuture(today)(date, ctx);
    }),
  });
}

export function buildUpdatePlantSchema(today: CalendarDate) {
  return UpdatePlantBaseSchema.extend({
    lastWateredOn: CalendarDateSchema.optional().superRefine((date, ctx) => {
      if (date !== undefined) lastWateredOnNotInFuture(today)(date, ctx);
    }),
  });
}

Every route that accepts lastWateredOn calls buildCreatePlantSchema(today) or buildUpdatePlantSchema(today) with the request's own today (Section 8.1) rather than validating against the base schema directly, so the future-date check is always evaluated against the correct APP_TIMEZONE-local "now."

The "at least one field must be provided" check no longer lives in this schema. Because NotesSchema now distinguishes an absent notes key from an explicit null (Section 9.4), the .refine() this schema used to carry for that check could never fail — value.notes was always undefined after parsing whether or not the caller sent it. Section 10.5 states that the route rejects a request with 400 VALIDATION_FAILED / UPDATE_EMPTY_BODY when the raw parsed JSON body, before any schema runs, contains none of the keys name, wateringIntervalDays, notes, lastWateredOn. By the time buildUpdatePlantSchema validates the body, the route has already established that at least one recognised key is present.

The 500-plant cap is a stateful check, not a schema rule. No Zod schema can know how many active plants already exist without a database read, so the create-plant route performs plantRepository.countActive() (Section 7.13) after schema validation passes and before the insert; if the count is already 500, the route returns 422 LIMIT_EXCEEDED with the message "You have reached the maximum of 500 plants" (cross-reference Section 13 for the envelope) without ever calling create. This check and the schema validation are independent: a request can pass every Zod rule and still be rejected here, and this rejection is never expressed as a Zod issue.

9.6 Error mapping #

Every validation failure — from any schema in Section 9.4 — becomes the canonical error envelope's details array (Section 13) via a single mapping function:

// apps/api/src/lib/zod-error.ts
import type { ZodError } from 'zod';

export interface ErrorDetail {
  path: string;
  message: string;
}

const MAX_DETAILS = 20;

export function zodErrorToDetails(error: ZodError): ErrorDetail[] {
  return error.issues.slice(0, MAX_DETAILS).map((issue) => ({
    path: issue.path.join('.'),
    message: issue.message,
  }));
}

• path is the dotted JSON path of the offending field (e.g. "wateringIntervalDays", or "plants.2.name" for the third element of the plants array in an import payload). A root-level refinement (such as the "at least one field must be provided" check in Section 9.5) has an empty path, rendered as "".
• message is exactly the human-readable string attached to the failing schema rule in Section 9.4 — never a raw Zod internal message like "Expected number, received string".
• Order follows the order error.issues reports them in, which Zod produces in the order fields are declared in the schema (top to bottom), so details is deterministic for a given input.
• A maximum of 20 entries are returned even if more fields fail; this bound exists so a pathologically malformed request (e.g. the import endpoint with hundreds of invalid rows) cannot produce an unbounded response body. details is omitted from the envelope entirely when it would be empty (Section 13), never sent as [].

9.7 Validation message catalogue #

This table is the catalogue of text carried in the API's error.message and error.details[].message (Section 13) — it is the server message catalogue, not the UI copy catalogue (Section 15.11 owns every client-rendered string). Every server-sent validation string in the product is one of the following, keyed by an identifier so no route composes its own wording for a condition already listed here:

Every route that produces a VALIDATION_FAILED error uses the message text from this table verbatim; no route composes its own wording for a condition already listed here. There is no IMPORT_TOO_MANY_PLANTS message: the 500-plant cap on import is the same stateful 422 LIMIT_EXCEEDED / PLANT_LIMIT_EXCEEDED check as plant creation (Section 9.5), evaluated in Section 24.5 after this schema passes, not a schema-level array-length cap. IMPORT_FUTURE_DATE_CLAMPED is produced by the import route, not by ImportPayloadSchema — Section 24.5 applies the future-date clamp to waterings[].wateredOn after this schema's structural validation passes, which is why ImportWateringSchema accepts any real calendar date without a not-in-the-future check.

9.8 Rejected-input test vectors #

The following inputs are rejected. This table is the direct source for the validation test suite named in Section 25; each row is one test case.

Each row's error code and HTTP status match the canonical error taxonomy in Section 13; no test vector in this table produces a code or status not already defined there.

10. Feature: Plant Management #

10.1 Feature summary and user value #

Plant management is the foundation of the product: a user builds and maintains the list of plants they own, each carrying just enough information to drive the due/overdue calculation in Section 8. Every other feature in this specification operates on the plant records created here. Without an accurate, low-friction way to add, correct, and remove plants, the due-tracking value of the app never materialises.

Capabilities included:

• Add a new plant with a name and a watering interval, optionally with notes and an initial last-watered date.
• View the full plant list with computed due status (see Section 12 for display behaviour).
• Edit any field of an existing plant.
• Soft-delete a plant, with a short-window undo.
• Restore a soft-deleted plant within 30 days.

10.2 The Plant DTO #

The Plant DTO is the canonical wire shape returned by every endpoint that returns a plant, in full, under the data key (or as an array element of data for the list endpoint). No endpoint returns a partial or summarised plant object; the shapes below are always complete.

type PlantStatus = 'overdue' | 'due_today' | 'due_soon' | 'upcoming';

interface Plant {
  id: string;                    // UUIDv7, canonical lowercase hyphenated form
  name: string;                  // 1-60 chars, trimmed, control chars stripped
  wateringIntervalDays: number;  // integer, 1-365
  notes: string | null;          // 0-2000 chars, trimmed, empty string normalised to null
  lastWateredOn: string;         // YYYY-MM-DD, local calendar date in APP_TIMEZONE
  nextDueOn: string;             // YYYY-MM-DD, computed, never stored
  daysUntilDue: number;          // computed, signed integer, negative means overdue
  daysOverdue: number;           // computed, 0 unless status is "overdue"
  status: PlantStatus;           // computed, see Section 8.3
  wateringCount: number;         // computed, count of rows in waterings for this plant
  createdAt: string;             // ISO 8601 UTC instant with milliseconds, e.g. "2026-05-02T09:11:04.220Z"
  updatedAt: string;             // ISO 8601 UTC instant with milliseconds
}

{
  "id": "01917f2c-8a3b-7c1e-9f4d-2b6e5a1c9d80",
  "name": "Monstera",
  "wateringIntervalDays": 7,
  "notes": "Living room, east window",
  "lastWateredOn": "2026-08-01",
  "nextDueOn": "2026-08-08",
  "daysUntilDue": 3,
  "daysOverdue": 0,
  "status": "upcoming",
  "wateringCount": 12,
  "createdAt": "2026-05-02T09:11:04.220Z",
  "updatedAt": "2026-08-01T07:44:52.010Z"
}

Every other section that refers to "a plant object" or "the Plant DTO" refers to this shape.

10.3 List plants #

GET /api/v1/plants returns every active (non-soft-deleted) plant. There is no query string, no filtering, and no pagination on this endpoint: Section 5 fixes a hard cap of 500 plants, which makes the full list cheap enough to always return whole. Sorting, filtering, and search are entirely client-side and are specified in Section 12.

• Ordering guarantee from the server: ascending created_at, then id as a stable tiebreak for rows created in the same millisecond. The client re-sorts for display per Section 12.3; the server order exists only to make "recently added" sort and pagination-free scrolling behaviour deterministic and independent of SQLite's default row order.

• Exclusion: rows with a non-null deleted_at are never included, regardless of purge state.

• Response:

  Copy

  {
    "data": [ /* Plant[], see Section 10.2 */ ],
    "meta": {
      "timezone": "America/Chicago",
      "today": "2026-08-05",
      "count": 2
    }
  }

  meta.timezone echoes the configured APP_TIMEZONE (Section 21). meta.today echoes todayInTimeZone(new Date(), APP_TIMEZONE) (Section 8.4) as computed by the server for this response. meta.count is data.length.

• Why today is echoed: the client's own device clock and timezone are not trusted for status computation (Section 8.4 lets the client optimistically recompute, but the server value always wins). Echoing today lets the client detect that local midnight has passed even if the visibilitychange/timer refresh in Section 16.5 has not yet fired, by comparing the previous response's meta.today to the new one and forcing a full status recomputation when they differ.

• An empty plant list returns 200 with "data": [] and "count": 0, never a 404.

10.4 Create a plant #

POST /api/v1/plants creates a plant and its first watering record in a single transaction.

Request body:

{
  "name": "Monstera",
  "wateringIntervalDays": 7,
  "notes": "Living room, east window",
  "lastWateredOn": "2026-08-01"
}

name and wateringIntervalDays are required. notes and lastWateredOn are optional. All field rules are defined once in Section 9 and enforced identically by the shared Zod schema on both client and server; this section only specifies the create-time behaviour built on top of that validation.

Processing steps, in order:

1. Validate the body against the shared CreatePlantInput Zod schema (Section 9). On failure, return 400 VALIDATION_FAILED with one details entry per failing field; no database work happens.
2. Count active plants (deleted_at IS NULL). If the count is already 500, return 422 LIMIT_EXCEEDED and stop. Creating the plant that brings the count from 499 to 500 succeeds; only the attempt that would exceed 500 is rejected.
3. Default lastWateredOn: if omitted, use todayInTimeZone(new Date(), APP_TIMEZONE) (Section 8.4). If supplied, it must pass the validation in Section 9 (not in the future, not before 1970-01-01).
4. Check for an existing active plant whose name, trimmed and compared case-insensitively, equals the new plant's trimmed name. A match does not block creation; it adds a warning (see below). Names are never required to be unique, by explicit product decision (Section 9).
5. Generate id as a UUIDv7 (application-side, per Section 4).
6. Insert the plants row: id, name, watering_interval_days, notes (or NULL), last_watered_on, created_at = now, updated_at = now, deleted_at = NULL.
7. Insert one waterings row in the same transaction: id (a second, independent UUIDv7), plant_id = plants.id, watered_on = plants.last_watered_on, created_at = now. This row exists so that the watering history (Section 11.4) and wateringCount never disagree with lastWateredOn: every plant's history contains at least one entry, and that entry is always the most recent lastWateredOn at the time it was set. Without it, a brand-new plant would show wateringCount: 0 while simultaneously reporting a lastWateredOn, which is an unexplained inconsistency to the user.
8. Commit the transaction. Both inserts happen inside one better-sqlite3 synchronous transaction (db.transaction(fn)); if step 7 were to fail (it cannot under normal operation, since the unique index in Section 7.4 cannot yet be violated by a plant's own first watering), step 6 rolls back too.
9. Return 201 with the created Plant DTO under data, a Location: /api/v1/plants/{id} header, and, when step 4 found a match, meta.warnings.

Response (success, no duplicate name):

HTTP/1.1 201 Created
Location: /api/v1/plants/01917f2c-8a3b-7c1e-9f4d-2b6e5a1c9d80
Content-Type: application/json; charset=utf-8

{ "data": { /* Plant DTO */ } }

Response (success, duplicate name):

{
  "data": { /* Plant DTO */ },
  "meta": {
    "warnings": [
      { "code": "DUPLICATE_NAME" }
    ]
  }
}

The warning object carries only the machine-readable code, never a message: the displayed text is owned exclusively by Section 15.11's form.name.duplicateWarning, so the server and the client can never drift into different wording. A warning is informational only: it never changes the HTTP status, never blocks the write, and is rendered in the UI as a dismissible inline notice, not a form error.

10.5 Update a plant #

PATCH /api/v1/plants/:plantId performs a partial update. Updatable fields: name, wateringIntervalDays, notes, lastWateredOn. id, createdAt, and all computed fields (nextDueOn, daysUntilDue, daysOverdue, status, wateringCount) are never accepted in the request body; if present, they are stripped as unknown/read-only fields per Section 5's unknown-field-stripping rule and simply ignored (not an error).

• Empty body: this check runs on the raw parsed JSON body, before schema validation, not as part of the Zod schema. If the raw body, after JSON parsing, contains none of the keys name, wateringIntervalDays, notes, lastWateredOn — including when it is {} or contains only unrecognised keys — the route rejects the request with 400 VALIDATION_FAILED and error code UPDATE_EMPTY_BODY before the shared UpdatePlantInput schema (Section 9) ever runs. Performing this check on the raw body, rather than on the schema's parsed output, is deliberate: it does not depend on how the schema normalises an omitted notes field, so it stays reachable regardless of that schema's internal behaviour.
• Partial semantics: any field omitted from the body is left unchanged. There is no way to "unset" name or wateringIntervalDays (they are always required to have a value); notes distinguishes "omitted" (left unchanged) from an explicit "notes": null or "notes": "" (both of which clear it to null), per the shared NotesSchema in Section 9.4.
• Derived values: nextDueOn, daysUntilDue, daysOverdue, and status are never sent in the request and are always recomputed fresh in the response from whatever lastWateredOn and wateringIntervalDays are in effect after the update. Section 8.8: shortening wateringIntervalDays can make a previously-upcoming plant instantly overdue; this is correct behaviour and is never clamped or blocked.
• updatedAt: set to now whenever the update changes at least one column. (The empty-body case above never reaches this point, since it is rejected before any column comparison.)
• Changing lastWateredOn: when the request includes a lastWateredOn different from the plant's current value, the API reconciles the watering history in the same transaction as the plant update:
  • It upserts a waterings row for the new date: if a row with watered_on equal to the new date already exists for this plant, nothing further happens to waterings; otherwise a new row is inserted with a fresh UUIDv7 id and created_at = now.
  • It never deletes any existing waterings row as a side effect of this upsert, even if the new lastWateredOn is earlier than existing entries. The history is a append-mostly log; editing lastWateredOn is treated as "record one more true watering event" (or "this event was already recorded, just correct the summary field"), not as a rewrite of history.
  • plants.last_watered_on is set to exactly the submitted value, regardless of whether it is chronologically the newest entry in waterings. nextDueOn is always computed from plants.last_watered_on, per Section 8.2, so this is what drives due-status.
  • There is no floor relating lastWateredOn to createdAt: an update may set lastWateredOn to any date that passes the Section 9 validation (not in the future, not before 1970-01-01), including a date earlier than the plant's own createdAt. A user correcting a plant they added late is a normal, expected case.
• Optimistic concurrency: the request may include an If-Unmodified-Since header. It is optional; omitting it means last-write-wins, with no conflict detection. When present:
  • Its value must be a valid HTTP-date per RFC 7231 (e.g. Wed, 05 Aug 2026 14:23:11 GMT). An invalid value returns 400 VALIDATION_FAILED with details: [{ "path": "If-Unmodified-Since", "message": "Must be a valid HTTP-date." }].
  • The server compares the header, truncated to the second, against the plant's current updatedAt, also truncated to the second (HTTP-date has no sub-second precision, so the comparison intentionally drops milliseconds). If they do not match, the update is rejected with 409 CONFLICT and the plant is not modified; the response body's error.message is "The resource was modified by another request. Reload and try again." and data is omitted (error responses never carry a data key, only the envelope in Section 13.2).
  • If they match, the update proceeds normally.

Request example (interval change only):

{ "wateringIntervalDays": 5 }

Response:

{ "data": { /* full Plant DTO with recomputed nextDueOn/status */ } }

10.6 Delete a plant #

DELETE /api/v1/plants/:plantId performs a soft delete.

1. The server looks up an active plant by id (WHERE id = ? AND deleted_at IS NULL). If none is found, return 404 NOT_FOUND. This covers both "id never existed" and "id belongs to an already-deleted plant" — the two are indistinguishable to the caller by design, since a soft-deleted plant is conceptually gone.
2. Set deleted_at = now and updated_at = now.
3. Return 204 No Content with an empty body.
4. The plant disappears from GET /api/v1/plants on the very next fetch (it was excluded by the query in Section 10.3 the instant deleted_at was set; there is no propagation delay).
5. Watering history rows for the plant are left untouched at this point; they are only removed at permanent purge time (step 7 below).
6. The client shows a toast with an Undo action for 10 seconds. Undo calls POST /api/v1/plants/:plantId/restore (Section 10.7). The 10-second window is a UI affordance only, enforced client-side; the restore endpoint itself has no such time limit (Section 10.7).
7. A maintenance task, running once at process start and then every 24 hours, permanently purges any plant whose deleted_at is more than 30 days in the past. Purging a plant hard-deletes the plant row and, via ON DELETE CASCADE on waterings.plant_id (Section 7.4), all of its watering rows. Purge is irreversible; there is no endpoint to recover a purged plant.
8. A second DELETE on the same plantId (whether immediately after the first or any time before purge) returns 404 NOT_FOUND, per step 1 — deleting an already-deleted plant is not idempotent in its response, only in its effect (the plant ends up deleted either way). See Section 13.8.

10.7 Restore a plant #

POST /api/v1/plants/:plantId/restore reverses a soft delete.

1. The server looks up a plant by id where deleted_at IS NOT NULL (i.e. it must currently be soft-deleted; restoring an already-active plant is not a valid operation). If no such row exists — because the id never existed, the plant was never deleted, or the plant has already been permanently purged — return 404 NOT_FOUND.
2. Eligibility window: restore has no independent time check of its own. It succeeds for as long as the row still physically exists, which in practice means "any time before the 30-day purge task in Section 10.6 step 7 runs for that row." A restore attempted at, say, day 29 succeeds. A restore attempted after purge has already run (which, given the task's 24-hour cadence, is any time from roughly day 30 to day 31 onward) returns 404 NOT_FOUND because the row is gone. The specification does not distinguish these 404 cases in the response; both simply mean "nothing to restore."
3. Set deleted_at = NULL and updated_at = now.
4. Name collisions: nothing special happens. Names are never unique (Section 10.4), so a restored plant sharing a name with another currently-active plant is a normal state. The restore response includes the same meta.warnings: [{ "code": "DUPLICATE_NAME", ... }] structure as create (Section 10.4) when such a collision exists at restore time, using the same case-insensitive, trimmed comparison.
5. Return 200 with the full, restored Plant DTO under data (with recomputed nextDueOn, daysUntilDue, daysOverdue, status based on the plant's unchanged lastWateredOn and wateringIntervalDays — time has passed since deletion, so a plant that was upcoming when deleted may now be overdue; this is expected and is not corrected or hidden).

{
  "data": { /* Plant DTO */ },
  "meta": { "warnings": [ { "code": "DUPLICATE_NAME" } ] }
}

10.8 Edge cases table #

10.9 Traceability #

11. Feature: Watering Actions and History #

11.1 The "Watered today" action #

POST /api/v1/plants/:plantId/waterings is the single primary action of the product — the one-tap button the user reaches for most often. It takes no meaningful request body: any body sent is ignored (unknown fields are stripped per Section 5, and this endpoint defines no accepted fields at all). The client never sends a date; the server alone determines "today," using todayInTimeZone(new Date(), APP_TIMEZONE) (Section 8.4), so that watering recorded from any device is anchored to the same clock regardless of the device's own timezone or clock drift.

Transaction, in order:

1. Look up the plant by id where deleted_at IS NULL. Not found → 404 NOT_FOUND.
2. Attempt to insert a waterings row: fresh UUIDv7 id, plant_id, watered_on = today, created_at = now.
3. If the insert succeeds (no conflict with the unique index on (plant_id, watered_on) from Section 7.4): update plants.last_watered_on = today and plants.updated_at = now.
4. If the insert conflicts (a watering for this plant on this date already exists): skip the update in step 3 entirely — see Section 11.2.
5. Commit. Both the insert and the plant update happen in one better-sqlite3 transaction.
6. Return 200 (not 201: this is an idempotent action endpoint that updates an existing resource's state, not a resource-creation endpoint in the REST sense) with the full, freshly recomputed Plant DTO under data, so the client needs no second request to refresh the row it just acted on. meta.wateringId is the id of the waterings row this call created — or, on the idempotent path (Section 11.2), the id of the pre-existing row for (plantId, today). meta.alreadyWateredToday is always present in this response and is false on this (the normal, non-idempotent) path. This is the only wire path by which the client learns a watering row's id; the Plant DTO (Section 10.2) never carries it.

{
  "data": {
    "id": "01917f2c-8a3b-7c1e-9f4d-2b6e5a1c9d80",
    "name": "Monstera",
    "wateringIntervalDays": 7,
    "notes": "Living room, east window",
    "lastWateredOn": "2026-08-05",
    "nextDueOn": "2026-08-12",
    "daysUntilDue": 7,
    "daysOverdue": 0,
    "status": "upcoming",
    "wateringCount": 13,
    "createdAt": "2026-05-02T09:11:04.220Z",
    "updatedAt": "2026-08-05T14:02:10.005Z"
  },
  "meta": { "alreadyWateredToday": false, "wateringId": "0191802a-1e4f-79aa-8b3c-4a2d7e9f1c02" }
}

11.2 Idempotency #

Watering a plant twice within the same local day (per APP_TIMEZONE) is idempotent:

• The second call returns 200 with meta.alreadyWateredToday: true and meta.wateringId set to the id of the pre-existing (plant_id, watered_on) row — the same value the first call returned, not a new one.
• No duplicate waterings row is created.
• plants.updated_at is not changed by the second call, because step 3 above only runs when the insert in step 2 actually happened. The response's data.updatedAt reflects whenever the row was last genuinely modified (which may be the first watering call, an earlier edit, or plant creation).
• When alreadyWateredToday is true, the client shows no Undo action for that call: undoing would delete a watering the user did not just create, since the row being referenced was created by an earlier call.

The guarantee is enforced at the database layer by the unique index (plant_id, watered_on) on the waterings table (canonical definition in Section 7.4), not by an application-level "check then insert" that could race. The insert in step 2 is attempted directly; a unique-constraint violation is caught and treated as the idempotent path, never as an error surfaced to the caller.

Double-tap race on a slow connection: because better-sqlite3 is a synchronous driver running in a single Node.js process handling one request at a time against the database, two near-simultaneous POST .../waterings requests for the same plant are still executed as two fully sequential transactions — there is no window in which both could observe "no row yet" and both attempt an insert that succeeds. The first transaction to reach step 2 inserts the row and updates the plant; the second transaction's insert then conflicts against a row that already exists, and it takes the idempotent path in step 4. The user sees two successful 200 responses and no error, regardless of tap timing.

11.3 Undo a watering #

The 10-second Undo affordance shown immediately after a "Watered today" tap calls DELETE /api/v1/plants/:plantId/waterings/:wateringId, using the id of the watering row created (or matched) by the action in Section 11.1. This is the same endpoint used for general history-entry deletion (Section 11.5); this subsection defines its behaviour once.

1. Look up the watering row by (plant_id, id). Not found → 404 NOT_FOUND. The client's Undo button treats this response as success — it dismisses the toast without an error, since the desired end state (the watering event no longer exists) already holds. This also covers the case where the watering was already deleted by an earlier Undo or a duplicate click.
2. Delete the row.
3. Recompute plants.last_watered_on, but only when the deleted row's watered_on equals the plant's current last_watered_on. If the deleted row was not the plant's current last_watered_on — for example, an older row left behind after a backdating edit (Section 10.5) — last_watered_on is left untouched, since the deleted row was never the value driving the due calculation.
   • When a recompute is needed and other waterings rows remain for the plant, set last_watered_on to the maximum (most recent) watered_on among the remaining rows.
   • When a recompute is needed and none remain (this was the plant's only watering record), set last_watered_on to the earlier of the plant's created_at (truncated to its calendar date in APP_TIMEZONE) and the plant's current last_watered_on. This floor rule (Section 8.2: lastWateredOn is never null) can therefore only preserve or increase how overdue the plant appears — it never advances last_watered_on to a later date, matching the rule that nothing silently un-overdues a plant (Section 12.8).
4. Set plants.updated_at = now.
5. Commit. Return 204 No Content.

Window enforcement: the "10 seconds" is a purely client-side UI affordance — a timer that hides the Undo button and lets the toast disappear. The DELETE endpoint itself imposes no time limit: an Undo request that reaches the server after the 10-second window (e.g. due to a slow network) still succeeds and still deletes the row, per the same rules as any other history deletion in Section 11.5. There is no server-side concept of "too late to undo."

11.4 Watering history retrieval #

GET /api/v1/plants/:plantId/waterings?limit=&offset= returns the plant's watering history, paginated. This is the only paginated collection in the API (Section 5).

• Path parameter: plantId — must reference a plant, active or soft-deleted (history remains viewable for a plant the user is mid-Undo on deleting; see Section 11.8 for the not-found cases).

• Query parameters: limit (integer, 1–100, default 20), offset (integer, ≥ 0, default 0). Both are validated by the shared Zod schema (Section 9); out-of-range or non-integer values are rejected — see Section 11.8.

• DTO:

  Copy

  { "id": "0191802a-1e4f-79aa-8b3c-4a2d7e9f1c02", "wateredOn": "2026-08-01", "createdAt": "2026-08-01T07:44:52.010Z" }

  Copy

  interface Watering {
    id: string;         // UUIDv7
    wateredOn: string;  // YYYY-MM-DD
    createdAt: string;  // ISO 8601 UTC instant
  }

• Ordering: watered_on descending, then created_at descending as a tiebreak. Under normal operation the unique index in Section 7.4 guarantees at most one row per (plant_id, watered_on), so the tiebreak is a defensive, deterministic default rather than one that is regularly exercised.

• Response:

  Copy

  {
    "data": [ /* Watering[] */ ],
    "meta": { "total": 12, "limit": 20, "offset": 0 }
  }

  meta.total is the full count of waterings rows for the plant, independent of limit/offset.

• "Show more" behaviour: the client requests the first page with limit=20&offset=0. Each subsequent "Show more" tap requests the next page with the same limit and offset advanced by limit, appending results to the list already rendered. The control is hidden once offset + data.length >= meta.total.

11.5 Deleting a history entry #

Deleting a specific watering history entry uses the same endpoint as Undo: DELETE /api/v1/plants/:plantId/waterings/:wateringId, specified in full in Section 11.3. The recomputation rules (most-recent-remaining, or floor to created_at's calendar date if none remain) apply identically regardless of which entry is deleted or how long ago it was recorded.

UI confirmation requirement: the client requires an explicit confirmation dialog ("Delete this watering record?") before calling this endpoint for any entry other than the single most recent one in the currently-loaded history list. Deleting the most recent entry within the 10-second post-water window is treated as an Undo and proceeds without a confirmation dialog (Section 11.3); deleting the most recent entry from the history list outside that window, or deleting any older entry, always requires confirmation, because it does not correspond to an action the user just took and is harder to mentally reverse.

11.6 What history is NOT #

Watering history exists solely to answer "when was this plant last watered" and to let a mistaken watering entry be corrected. It is not an analytics feature: this specification never surfaces charts, streaks, running averages, or summary statistics such as "you water this plant every 6.2 days on average." Watering history analytics of any kind beyond the basic due/overdue status is explicitly out of scope for this product (Section 3.2), and no future-work language elsewhere in this document implies otherwise.

11.7 Worked history scenarios #

Scenario 1 — Plant creation seeds the first entry. Plant "Fern" created 2026-07-01 with wateringIntervalDays: 7, no lastWateredOn supplied (defaults to today, 2026-07-01).

Scenario 2 — "Watered today" tapped twice on the same day. Continuing Scenario 1, on 2026-07-08 the user taps "Watered today," then taps it again by accident.

Scenario 3 — Undo the most recent watering. Continuing Scenario 2, the user immediately taps Undo on the 2026-07-08 entry.

Scenario 4 — Deleting a middle entry has no effect on lastWateredOn. Plant "Pothos" has three waterings: 2026-06-01, 2026-06-15, 2026-07-01 (most recent). plants.lastWateredOn = 2026-07-01. The user deletes the 2026-06-15 entry from the history list (with confirmation, per Section 11.5).

Scenario 5 — Deleting the last remaining entry floors to createdAt. Plant "Cactus" created 2026-01-10, with exactly one watering row (2026-01-10, from creation) and no "Watered today" taps since. plants.lastWateredOn = 2026-01-10. The user deletes that single history entry.

Scenario 6 — Deleting the only entry after later corrections. Plant "Aloe" created 2026-02-01. On 2026-02-01 the user immediately edits lastWateredOn to 2026-01-20 (a backdated correction, per Section 10.5), which upserts a waterings row for 2026-01-20 (the creation-time row for 2026-02-01 already exists and is left in place, per the upsert-never-deletes rule). The user then deletes the 2026-02-01 row, leaving only 2026-01-20. Finally, the user deletes the 2026-01-20 row too.

11.8 Edge cases table #

12. Feature: Due and Overdue Status Display #

12.1 What the user must be able to answer in three seconds #

Opening the app, the user must be able to answer "what needs water right now" without reading every row. Three mechanisms work together to deliver this, each specified below: the summary bar (12.2) gives the answer as a single sentence before any row is read; the default urgency sort (12.3) puts everything requiring action at the top of the list, in order of severity; and the highlighting rules (12.7) make overdue and due-today rows visually distinct at a glance, without requiring the user to read status text on every row.

12.2 The summary bar #

A single line rendered above the plant list, above any sort/filter/search controls. "Needs water" means status overdue or due_today only (Section 6.4) — due_soon and upcoming plants are never counted here, since the bar's purpose is to answer "what do I need to do today," not "what's on the horizon."

The exact copy for the zero/one/many cases is canonical in Section 15.11 (summary.zeroDue, summary.oneDue, summary.manyDue); this section does not restate it.

The count is recomputed on every plant-list refresh (Section 16.5) and updates immediately after any mutation that changes a plant's status (watering, editing the interval, deleting, restoring).

12.3 Sorting #

The default list order is urgency, computed entirely client-side from the Plant DTOs returned by GET /api/v1/plants (which are server-ordered by created_at, per Section 10.3, but always re-sorted before display).

Comparator decision table (evaluated top to bottom; the first row that distinguishes two plants decides their order):

Tier order itself is fixed: overdue < due_today < due_soon < upcoming, matching the urgency order defined in Section 8.4.

The comparator itself is the single shared compareByUrgency function defined once in Section 8.4, which this section does not redefine or duplicate; it implements exactly the decision table above, including the id-ascending absolute tiebreak and a collator pinned to 'en' with { sensitivity: 'base' } so list order is identical across every host locale, including CI.

User-selectable sorts, in addition to the default urgency sort, exposed via a control the user can change at any time:

The chosen value is persisted in localStorage under the key hpt.sort and restored on next visit. An absent or invalid stored value falls back to 'urgency'.

12.4 Filtering #

A Show select (Section 16.2) with options "All plants" and "Needs water" filters the displayed list to plants whose status is overdue or due_today (the identical predicate used by the summary bar in Section 12.2). It does not affect the summary bar's count, which always reflects the full unfiltered list.

The selected value is persisted in localStorage under the key hpt.filter, with values 'all' (default, no filtering) and 'needs-water'. An absent or invalid stored value falls back to 'all'.

When the filter is active and matches no plants, the list area shows the copy canonical in Section 15.11 (emptyState.noDueMatches); this section does not restate it.

12.5 Search #

A text input appears above the list when the unfiltered active plant count exceeds 10 or the current search query is non-empty — this threshold is evaluated against the total number of active plants returned by the API, independent of whether the "Needs water" filter (12.4) is currently on, so the search control does not flicker in and out of existence as the filter is toggled.

• Disappearing while a query is active: if the active plant count later falls to 10 or fewer while a search query is non-empty (for example, the user deletes a plant), the query is reset to the empty string, the input unmounts, the full list re-renders, and — if focus was inside the search input — focus moves to the SummaryBar (tabindex="-1"). Resetting the query rather than leaving it applied with no visible control prevents plants from silently disappearing from the list with no way to see why.

• Matching: client-side, case-insensitive, diacritic-insensitive substring match against name only. notes is never searched, since notes are meant as free-form private context, not an index.

• Normalisation function, applied identically to the query and to each candidate name before substring comparison:

  Copy

  function normalizeForSearch(value: string): string {
    return value
      .normalize('NFD')
      .replace(/[̀-ͯ]/g, '') // strip combining diacritical marks
      .toLowerCase();
  }

  Example: a search for "monstera" matches a plant named "Monstéra".

• Debounce: 150 ms after the last keystroke before the filter re-applies. The debounce is a pure UI responsiveness detail — search runs entirely client-side over already-loaded data, so it never triggers a network request.

• Combination with the "Needs water" filter: the two apply with logical AND. A plant must match the search text (if any) and pass the filter (if active) to be shown.

• Empty result copy: canonical in Section 15.11 (emptyState.noResults), interpolated with {query} — the raw, non-normalised text the user typed, HTML-escaped by React's default text rendering. This section does not restate the string.

12.6 The status badge #

Every plant row carries a status badge combining an icon and a text label, with the label carrying the day count for overdue. Label copy comes from the shared formatRelativeDueLabel function (Section 8.4) so the wording used in the badge, in any alert text, and anywhere else a status is described in prose is generated from one place, never hand-duplicated. The badge is the only status label rendered in the row — no separate line duplicates or abbreviates it elsewhere in the row markup:

The icon is decorative (aria-hidden="true") and the label text is what a screen reader announces — there is no separate, redundant "icon name" announcement. See Section 19 for the full accessibility treatment.

12.7 Highlighting rules #

A plant row is visually distinguished from a non-urgent row using four coordinated signals, none of which is colour alone (satisfying WCAG 2.2 success criterion 1.4.1; the design tokens are canonical in Section 15):

1. A left border accent, 4px wide, in the status colour (Section 15 defines the exact tokens; this section only defines that the accent exists and which status it maps to).
2. A tinted background surface for the whole row, using the paired surface-tint token for that status.
3. The status badge from Section 12.6, which combines an icon and a text label.
4. For overdue specifically, the numeric day count is always shown as part of the badge text, never omitted even when space is tight — "Overdue" alone is insufficient information.

Non-colour redundancy requirement: removing colour entirely (e.g. a grayscale rendering, or a user with a colour-vision deficiency) must not remove any information. Verifying this is testable by confirming that the icon and text label alone, with colour desaturated, still let a user distinguish all four statuses. See Section 19 for the automated and manual accessibility checks that enforce this.

12.8 Overdue never resets #

Restating the binding rule from Section 6.6: nothing in the system silently advances lastWateredOn, and no status "expires" or resets itself with the passage of time — a plant only leaves the overdue state when the user explicitly waters it (Section 11.1) or edits its lastWateredOn/wateringIntervalDays (Section 10.5).

Worked example: a plant with wateringIntervalDays: 14, last watered 104 days ago and never watered since. daysUntilDue = 14 - 104 = -90, so daysOverdue = 90 and status = 'overdue'. It reads "Overdue by 90 days" (Section 12.6), sorts to the very top of the default urgency list (Section 12.3, tier 1, daysOverdue descending), and is counted in the summary bar (Section 12.2). Every one of these facts remains exactly true, day after day, with no change, until the user takes an explicit action on the plant. On day 105 it reads "Overdue by 91 days"; nothing about the mechanism changes.

12.9 Edge cases #

13. API Design and Contract #

13.1 Conventions #

• Base path: /api/v1. Every JSON endpoint in this specification lives under it; there is no unversioned or v2 surface.
• Versioning policy: the version segment is part of the path, not a header. This product will only ever ship a v1; introducing a v2 API is explicitly a rejected non-requirement.
• Casing: all JSON keys, in requests and responses, are camelCase. The database uses snake_case (Section 7); a repository/mapper layer converts between the two, and snake_case never appears on the wire.
• Content type: the media type must be application/json; a charset=utf-8 parameter is permitted (and is what every response sets). A request with a body whose media type is anything else is rejected with 415 UNSUPPORTED_MEDIA_TYPE before the body is parsed.
• Non-object JSON bodies: a request body that parses successfully as JSON but is not a JSON object — null, an array, a string, a number, or a boolean — is rejected with 400 MALFORMED_JSON and message id MALFORMED_JSON_BODY. This check runs in the body parser, before the route's Zod schema ever sees the body, so it is distinguished from a body that is a JSON object but fails field-level validation (which yields VALIDATION_FAILED instead).
• Trailing slashes: rejected. Fastify is configured with ignoreTrailingSlash: false; a request to /api/v1/plants/ (trailing slash) returns 404 NOT_FOUND, distinct from and not silently redirected to /api/v1/plants.
• Unknown fields: stripped, not rejected. Every request-body Zod schema uses .strip() (the Zod v3 default for plain objects), so an unrecognised key in the body is silently dropped before validation of the recognised keys proceeds. This is a deliberate leniency: it lets older clients send extra fields without breaking, at the cost of never warning about typos in field names. Field name typos are instead caught by required-field validation when the correctly-named field is therefore missing.
• Body size caps: 64 KB for every endpoint except POST /api/v1/import, which allows up to 5 MB (Section 24 defines the import format; the size allowance exists to admit a full data export re-imported as a backup restore). A body exceeding the applicable cap is rejected with 413 PAYLOAD_TOO_LARGE before parsing.

13.2 Success and error envelopes #

Every response body, success or error, is a JSON object at the top level. No endpoint ever returns a bare array or a bare scalar — a list is always { "data": [...] }, never a top-level [...]; a count or boolean is always nested under data or meta, never returned as a bare JSON number, string, or boolean.

Success envelope:

{
  "data": { /* or [] for list endpoints, or omitted entirely for 204 responses */ },
  "meta": { /* optional; present only where a specific endpoint in Section 13.5 defines it */ }
}

• meta is omitted entirely when an endpoint has nothing to put in it (e.g. GET /api/v1/health returns only data).
• HTTP status is 200 for reads and updates, 201 for creates, 204 with a fully empty body (no data, no meta, zero bytes) for deletes.

Error envelope — the only error shape used anywhere in the API:

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Human-readable, one sentence, safe to display.",
    "details": [ { "path": "wateringIntervalDays", "message": "Must be between 1 and 365." } ],
    "requestId": "01917f2c-8a3b-7c1e-9f4d-2b6e5a1c9d80"
  }
}