steveandClaude Opus 4.8
81481ede2f
"German Red Garlic" now links back to the Johnny's page it came from, and pansy knows how much is left. Two modelling calls, both of which look like omissions unless stated. The plant catalog stays FLAT — no species/variety hierarchy. A row in your catalog just is the thing you plant; the built-in "Garlic" is a generic starting point you clone. A hierarchy buys taxonomy nobody asked for and complicates every join. Inventory belongs to a PURCHASE, not to a variety. You might buy the same garlic from two vendors in two years at two prices and two germination rates; quantity columns on plants would collapse all of that into one number and lose it. So lots get their own table, and owner_id sits on the lot rather than being inherited from the plant — you can buy generic built-in Garlic from Johnny's and the record is still yours alone. Lots are never shared along with a garden. `remaining` is derived, never stored: quantity minus the summed effective count of the active plantings attributed to the lot. The alternative — decrementing a column when you plant — drifts the moment anything edits or removes a planting behind its back, and once it has drifted there's no way to tell what the true number was. Removing a plop gives the seed back with nothing having to remember to. The usage query returns raw radius/count/spacing rather than a SUM, because the effective-count formula lives in the service and reproducing it in SQL would guarantee the two drift apart. source_url is validated as http(s) with a host, on both plants and lots. It renders as a clickable link, so that check is load-bearing rather than tidiness: without it a stored javascript: URL becomes script execution the moment someone clicks it. Schemeless and relative URLs are refused too — they'd resolve against pansy's own origin, which is never what a vendor link means. A planting's lot must be the actor's AND a lot of the plant being planted. Attributing a garlic planting to a tomato lot would silently corrupt every remaining count downstream, so it's refused rather than stored, and re-checked on update in case a plant swap invalidated a previously-valid attribution. Deleting a lot leaves its plantings alone with a null link: the plants really were in the ground, whatever happened to the record of the packet. Closes #50 Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]> Claude-Session: https://claude.ai/code/session_01H3zbym8Doka2d7D48maSgZ
132 lines
14 KiB
Markdown
132 lines
14 KiB
Markdown
# Pansy — Design
|
||
|
||
Pansy is a self-hostable garden planning web app. A landscaping-style 2D editor: drag garden objects (raised beds, grow bags, containers, in-ground plots, trees, paths) onto a field at real-world scale; click into a plantable object to place freeform "plops" of plants — a few plops of garlic in one corner, herbs in another, beans along a side — and zoom out to still see what's planted where. React frontend, Go backend, clean JSON API, single static binary. Works on desktop and is mobile-usable (touch drag, pinch zoom).
|
||
|
||
Work is tracked in Gitea issues; the tracking epic links every piece in dependency order.
|
||
|
||
## Decisions
|
||
|
||
- **Placement model:** freeform plops (not a square-foot grid), scaled by real plant spacing. Grid snapping may come later as a toggle.
|
||
- **Stack:** Go 1.26.x backend, module `gitea.stevedudenhoeffer.com/steve/pansy`; React + TypeScript + Vite + Tailwind frontend, production build embedded via `embed.FS` → one static binary (`CGO_ENABLED=0`).
|
||
- **Users:** multi-user with ownership. Users own gardens; a garden can be shared with other users as viewer (read) or editor (edit content). Owner additionally shares/deletes.
|
||
- **Auth:** OIDC-first (Authentik is the primary IdP), local argon2id passwords as an optional fallback.
|
||
- **Agentic future:** integration with majordomo/executus via typed Go tools (`llm.DefineTool[Args]`) wrapping the same service layer the REST API uses — not MCP/OpenAPI.
|
||
|
||
## Domain model
|
||
|
||
SQLite, centimeters everywhere (display-side imperial conversion only), `version INTEGER` on every user-mutable row for conflict detection.
|
||
|
||
- **users** — email (unique), display_name, nullable argon2id `password_hash`, nullable `oidc_issuer`+`oidc_subject` (unique pair), `is_admin`. First registered user becomes admin. `PANSY_REGISTRATION` (open/closed) gates local signup. A user can be local-password, OIDC, or both (linked by email on first OIDC login).
|
||
- **sessions** — sha256-hashed random 32-byte token, user_id, 30-day sliding expiry. HttpOnly cookie holds the raw token. Sessions are pansy-local regardless of auth method.
|
||
- **gardens** — owner_id, name, width_cm, height_cm, unit_pref (`metric`|`imperial`), notes.
|
||
- **garden_shares** — (garden_id, user_id) unique, role `viewer`|`editor`, created_by. Owner is implicit via `gardens.owner_id`, never a share row.
|
||
- **garden_objects** — one polymorphic table: `kind` (`bed`|`grow_bag`|`container`|`in_ground`|`tree`|`path`|`structure`), name, `shape` (`rect`|`circle`; `polygon` + `points` JSON reserved in schema, not in the v1 editor), center `x_cm`,`y_cm` in garden space, `width_cm`,`height_cm` (circle: width=diameter), `rotation_deg`, `z_index`, `plantable` bool, nullable `color` override, `props` JSON for kind-specific extras (bed height, tree species…), notes.
|
||
- **seed_lots** — one purchase: vendor, source URL, sku, lot code, purchase date, packed-for year, quantity + unit, cost, germination %. `owner_id` is on the LOT, not inherited from the plant, so you can record buying generic built-in Garlic from Johnny's and keep it private. `plantings.seed_lot_id` (ON DELETE SET NULL) attributes a plop to a purchase; **`remaining` is derived** (quantity − summed effective count of active plantings), never stored — a decremented column drifts the moment a planting is edited behind its back and can't be audited afterwards. Lots are never shared along with a garden.
|
||
- **plants** — catalog, plus `source_url`/`vendor` provenance for the variety itself. `owner_id NULL` = built-in (~30 seeded via migration, read-only, clone to customize). name, category (`vegetable`|`herb`|`flower`|`fruit`|`tree_shrub`|`cover`), `spacing_cm` (mature spacing), `color` hex, `icon` (emoji string — zero assets in v1), nullable `days_to_maturity`, notes. Users see built-ins + their own.
|
||
- **change_sets** / **revisions** — the undo substrate. A change set groups the row-level revisions one logical operation produced (`source` ui/agent/api, `summary`, nullable `agent_run_id`, nullable `reverts_id`); a revision is `(entity_type, entity_id, op, before, after)` with full JSON row snapshots. The unit of undo is the **operation, not the row**. Revert is itself a change set, so an undo can be undone; it is version-guarded per entity and reports conflicts rather than clobbering a later edit. Garden *deletion* is deliberately not revertible (the cascade is invisible to the service, and would take the history with it).
|
||
- **plantings** ("plops") — object_id, plant_id, center `x_cm`,`y_cm` **in the parent object's local frame** (moving/rotating a bed moves its plants for free), `radius_cm` (a plop is a circular patch), nullable `count` (NULL = derived: `max(1, round(π·r² / spacing_cm²))`), nullable label, `planted_at`/`removed_at` dates. "Clear bed" sets `removed_at`; v1 shows rows where `removed_at IS NULL`. Year-over-year history and a future plan/scenario layer build on these dates without schema surgery.
|
||
|
||
## Geometry
|
||
|
||
- Garden space: origin top-left, x→right, y→down (screen-aligned), cm.
|
||
- Objects: positioned by **center point** + `rotation_deg` clockwise about center → SVG `translate(x y) rotate(deg)` one-liners.
|
||
- Object local frame: origin at object center, axes aligned to the unrotated object. Plops live in this frame.
|
||
- Exactly two nesting levels: garden → object → plop. No recursive containers.
|
||
- API and DB are metric-only; cm ↔ ft/in conversion is purely a frontend display concern.
|
||
|
||
## Editor / rendering
|
||
|
||
- **Plain SVG in React.** Tens of objects + low-hundreds of plops is far below SVG's ceiling; native DOM hit-testing, Tailwind styling, crisp text at any zoom. No Konva/canvas.
|
||
- **One gesture library: `@use-gesture/react`** for unified drag / wheel-zoom / pinch on desktop + touch. Everything else is hand-rolled pointer math.
|
||
- Viewport = a single `<g transform="translate(tx,ty) scale(s)">`; state `{tx, ty, scale}` where scale = px per cm. Wheel/pinch zooms to cursor; drag on empty space pans; drag on an element moves it.
|
||
- **Field view and bed interior are the same canvas.** "Click into a bed" animates the viewport to fit the object and sets `focusedObjectId` (mirrored to `?focus=` URL param for deep links). Focused mode dims siblings and enables plop placement; Escape/tap-out zooms back.
|
||
- **Semantic zoom**, three bands by scale (thresholds tuned by feel):
|
||
- zoomed out (< ~0.75 px/cm): plops render as flat color patches; plantable objects show name + dominant-plant color — "what's planted where" at a glance;
|
||
- mid: plops as colored circles with the plant's emoji icon;
|
||
- zoomed in (> ~3 px/cm): icon + plant name + count per plop.
|
||
|
||
## API
|
||
|
||
REST under `/api/v1`, JSON, cookie-session auth (HttpOnly, SameSite=Lax, Secure under TLS). Gin with slog-gin + Recovery; embedded SPA fallback for non-`/api` routes.
|
||
|
||
```
|
||
POST /auth/register | /auth/login | /auth/logout GET /auth/me GET /auth/providers
|
||
GET /auth/oidc/login GET /auth/oidc/callback (authorization-code + PKCE)
|
||
GET,POST /gardens GET,PATCH,DELETE /gardens/:id
|
||
GET /gardens/:id/full ← one-shot editor load: garden + objects + plantings + referenced plants
|
||
GET /gardens/:id/history ← change sets, newest first (paginated)
|
||
POST /change-sets/:id/revert ← undo an operation; 201, or 409 + the conflicts it skipped
|
||
POST /gardens/:id/copy ← deep-copy a garden you own (objects + active plops; not shares/link)
|
||
POST /gardens/:id/objects PATCH,DELETE /objects/:id
|
||
POST /objects/:id/plantings PATCH,DELETE /plantings/:id
|
||
GET,POST /plants PATCH,DELETE /plants/:id (own plants only)
|
||
GET,POST /seed-lots GET,PATCH,DELETE /seed-lots/:id (own lots only; private)
|
||
GET,POST /gardens/:id/shares PATCH,DELETE /gardens/:id/shares/:userId (invite by email)
|
||
```
|
||
|
||
**Sync:** plain REST + optimistic UI + last-write-wins with a version guard. Every PATCH/DELETE carries the row's `version`; the server increments on write and returns **409 + the current row** on mismatch; the client rolls back and refetches. No websockets/CRDT — the right cost for household-scale co-editing. Drags PATCH once on drop, not per frame.
|
||
|
||
## Backend layout
|
||
|
||
**Storage:** `modernc.org/sqlite` (pure Go) + hand-written SQL via `database/sql`. WAL mode + `busy_timeout=5000` (open pattern per executus `contrib/store/sqlite.go`). Migrations are numbered `.sql` files in an `embed.FS` with a tiny runner and a `schema_migrations(version)` table, run at startup; seed plants live in a migration.
|
||
|
||
```
|
||
cmd/pansy/main.go config load → store.Open → migrate → service → api → ListenAndServe
|
||
internal/config/ PANSY_PORT, PANSY_DB, PANSY_BASE_URL, PANSY_REGISTRATION,
|
||
PANSY_OIDC_* (issuer/client_id/secret/button label), PANSY_LOCAL_AUTH,
|
||
trusted proxies
|
||
internal/store/ sqlite.go (open/pragmas), migrate.go, migrations/*.sql (embedded),
|
||
queries per entity (users.go, gardens.go, objects.go, plantings.go,
|
||
plants.go, shares.go)
|
||
internal/domain/ plain structs + sentinel errors (ErrNotFound, ErrForbidden,
|
||
ErrVersionConflict)
|
||
internal/service/ ★ THE SEAM. All permission checks + business ops. auth.go, gardens.go,
|
||
objects.go, plantings.go, plants.go, shares.go, ops.go (FillRegion etc.),
|
||
revisions.go (change-set scoping, recording, revert)
|
||
internal/api/ thin gin handlers (decode → service → encode), session middleware,
|
||
ginserver setup, routes.go, oidc.go, spa.go (embed fallback)
|
||
internal/webdist/ dist.go: //go:embed all:dist (web build copied in by Makefile)
|
||
internal/agent/ later: llm.DefineTool[Args] wrappers over the SAME service methods
|
||
web/ Vite app
|
||
Makefile (cd web && npm run build) → copy dist → CGO_ENABLED=0 go build
|
||
```
|
||
|
||
**Every mutation is recorded.** Service mutations call `record(...)`, which joins the change set on the context if one is open and otherwise opens a single-op one for that mutation alone. That auto-scope is what keeps undo shallow: REST handlers need no changes at all, and only the agent wraps a whole turn (`WithChangeSet`) so a multi-step turn undoes as one unit. A multi-row operation passes all its changes in one `record` call for the same reason.
|
||
|
||
**The service seam is the point.** Every operation is a method on `*service.Service` taking `(ctx, actorUserID, args)`; all ACL checks live there, not in handlers. REST handlers are thin adapters; future agent tools are equally thin `llm.DefineTool[Args]` adapters over the same methods — so agent calls inherit permission enforcement for free. Bulk ops designed for agents from the start, e.g. `FillRegion(ctx, actor, objectID, region, plantID, spacingOverride)` with `region` a rect/circle in object-local coordinates.
|
||
|
||
### Auth
|
||
|
||
- **OIDC (primary; Authentik).** `github.com/coreos/go-oidc/v3` + `golang.org/x/oauth2` (pure Go). Authorization-code flow with PKCE + `state` cookie; issuer discovery from `PANSY_OIDC_ISSUER`; redirect URI derived from `PANSY_BASE_URL`. JIT provisioning on first login (the IdP gates access, so the registration flag doesn't apply); the email claim links to an existing local account if one matches, otherwise a user is created and stamped with `oidc_issuer`/`oidc_subject`.
|
||
- **Local (fallback).** argon2id (`x/crypto/argon2`, id variant), `subtle.ConstantTimeCompare`. Disable entirely with `PANSY_LOCAL_AUTH=false` for pure-Authentik deployments.
|
||
- Both paths end in the same pansy session cookie. `GET /auth/providers` tells the login page which methods to show.
|
||
|
||
## Frontend layout
|
||
|
||
React 19 + TypeScript + Vite + Tailwind 4 (`@tailwindcss/vite`), `@tanstack/react-router`, `@tanstack/react-query`, zod for API parsing; dev proxy `/api` → Go server.
|
||
|
||
- **Routes:** `/login`, `/register`, `/gardens` (list), `/gardens/:id` (editor, `?focus=objectId`), `/plants` (catalog). Auth guard on the router root via `/auth/me`.
|
||
- **State:** TanStack Query for all server state (editor keyed on `gardens/:id/full`; optimistic mutations with version-conflict rollback). One small Zustand store for ephemeral editor state only: viewport, selection, focused object, active tool, in-flight drag.
|
||
- **Editor components (`web/src/editor/`):** `GardenCanvas` (svg root + viewport g), `useViewport` (use-gesture pan/zoom/pinch), `ObjectShape`, `PlopMarker` (semantic-zoom branching), `Palette` (drag-to-place object kinds), `Inspector` (side panel; bottom sheet on mobile), `PlantPicker`. Pure geometry helpers (local↔world transforms, unit formatting) in `web/src/lib/geometry.ts`, unit-tested.
|
||
|
||
## Roadmap
|
||
|
||
1. **Scaffold** — Go module, config, gin server, healthz, sqlite + migration runner; Vite/Tailwind/router shell; embed.FS single-binary build.
|
||
2. **Auth** — OIDC (Authentik) + local fallback, sessions, route guard.
|
||
3. **Gardens** — CRUD + list page; establishes service-layer and version/409 conventions.
|
||
4. **Field editor** — objects, canvas, pan/zoom/pinch, palette, move/resize/rotate, optimistic sync. *Riskiest slice — test on a phone at the end of it, not later.*
|
||
5. **Plant catalog** — ~30 seeded built-ins + custom plants.
|
||
6. **Plops** — focus-zoom, place/move/resize, derived counts, semantic zoom. *The core vision lands here.*
|
||
7. **Sharing** — invite by email, roles, viewer read-only mode.
|
||
8. **Polish** — imperial toggle, mobile ergonomics, clear-bed, keyboard nudging.
|
||
9. **Agent seam** — `ops.go` bulk ops + `internal/agent` DefineTool wrappers; optional mort-style API-key agent endpoint. The agent harness itself lives in majordomo/executus, outside pansy.
|
||
|
||
## Deliberate v1 limits
|
||
|
||
1. Plop `count` derived from area ÷ spacing², explicit override allowed.
|
||
2. Shapes: rect + circle only (polygon reserved in schema).
|
||
3. Seasons = planted/removed dates; a scenario/year-plan layer is future work these dates don't block.
|
||
4. Emoji plant icons (zero assets); SVG icon set later if wanted.
|
||
5. No background/satellite image tracing (cheap to add later as a garden background field).
|
||
6. 409-and-refetch conflict handling; no real-time sync.
|