bloombase/docs/superpowers/specs/2026-05-27-plantdb-design.md

PlantDB — Design Spec

Date: 2026-05-27 Stack: Django 5 + Bootstrap 5 + HTMX Deployment: Docker Compose on homelab

---

1. Overview

PlantDB is a mobile-first family plant and flower registry. It tracks both indoor and outdoor plants, stores care information per species, surfaces a pruning calendar, and integrates with the Perenual API to auto-populate species data. No user accounts — a single shared instance for the whole family.

---

2. Architecture

Browser (mobile-first)
    │  Bootstrap 5 + HTMX (partial page updates)
    ▼
Nginx (reverse proxy + static/media files)
    ▼
Gunicorn + Django 5
    ▼
SQLite (single file, Docker volume)
    │
    └── Perenual API (external, cached on first lookup)

Key principles:

• Server-rendered Django templates throughout; HTMX handles dynamic interactions (species search live results, pruning log updates) without a separate API layer.
• Perenual API is called only once per species — results are cached in the Species table. No recurring API cost after initial lookups.
• All uploaded media (personal plant photos) stored in a Docker volume and served by Nginx.

---

3. Data Model

Species

Populated from Perenual API or entered manually. One row per plant species.

Field	Type	Notes
id	PK
common_name	CharField
scientific_name	CharField
description	TextField
watering	CharField	e.g. "Weekly", "Twice a week"
sunlight	CharField	e.g. "Full sun", "Partial shade"
shadow_tolerance	CharField	e.g. "Low", "Medium", "High"
max_height_cm	IntegerField	nullable
growth_rate	CharField	e.g. "Slow", "Moderate", "Fast"
growth_season	CharField	e.g. "Spring–Summer"
pruning_months	JSONField	Default schedule, e.g. [2, 6, 8] — pre-fills the Plant field
api_image_url	URLField	Image from Perenual, nullable
perenual_id	IntegerField	Unique, nullable — prevents duplicate fetches

Plant

One row per physical plant owned by the family.

Field	Type	Notes
id	PK
name	CharField	User's nickname, e.g. "Big rose on back fence"
species	FK → Species	Nullable — plant can exist without a species link
location	CharField	Free text, e.g. "Living room windowsill"
is_indoor	BooleanField
pruning_months	JSONField	This plant's actual pruning schedule — pre-filled from species, editable per plant
photo	ImageField	Personal photo, stored in media volume, nullable
notes	TextField	Free text, nullable
date_added	DateField	Auto-set on creation

PruningLog

One row per pruning event, logged by the family.

Field	Type	Notes
id	PK
plant	FK → Plant
pruned_on	DateField
notes	TextField	nullable

---

4. Pages & Views

Dashboard (home /)

• Summary tiles: total plant count, number of plants due for pruning this month.
• Upcoming pruning list: overdue plants first (red), then due this month (amber).
• Buttons: "View all plants", "Add plant".
• HTMX: none needed — static server render on load.

Plant List (/plants/)

• Scrollable list of all plants, each showing name, location, indoor/outdoor badge, and thumbnail.
• Search bar at top — HTMX live search filters the list on each keystroke (targets the list partial).
• Filter chips: All / Indoor / Outdoor.
• FAB-style "+" button links to Add Plant.

Plant Detail (/plants/<id>/)

• Full-width personal photo hero (falls back to API species image if no personal photo).
• Name, scientific name (italic), indoor/outdoor badge.
• Location line.
• Care chips: 💧 watering · ☀️ sunlight · 📏 max height.
• Species reference image (small, below care info) if API image available and personal photo also exists.
• Pruning strip: recommended months + last pruned date. Amber highlight if due this month, red if overdue.
• "Log pruning" button → inline HTMX form (date + optional notes), updates pruning strip on success.
• Pruning history accordion: list of all PruningLog entries for this plant.
• Edit and Delete actions.

Add Plant (/plants/add/)

Two-step flow:

Step 1 — Species search (optional)

• Search input with HTMX live lookup against Perenual API (debounced, 300ms).
• Results show common name, scientific name, thumbnail.
• Selecting a result caches the species in the DB (if not already cached) and pre-fills the form.
• "Skip — enter manually" link bypasses to step 2 with a blank form.

Step 2 — Plant form

• Nickname field (required).
• Location field (free text).
• Indoor/Outdoor toggle.
• Care fields (watering, sunlight, etc.) — pre-filled from species if selected, all editable.
• Pruning months — pre-filled from species, shown as a 12-checkbox month picker.
• Photo section: "Take photo" (camera capture via <input type="file" accept="image/*" capture="environment">). The species API image, if available, is always shown automatically on the plant detail as a reference — no separate action needed.
• Notes textarea.
• Save button.

Edit Plant (/plants/<id>/edit/)

Same form as Add, pre-populated.

Pruning Calendar (/pruning/)

• Grouped by urgency:
  1. Overdue (red) — plants with a recommended pruning month in the past and no log entry since.
  2. This month (amber) — plants with current month in pruning_months.
  3. Next month (grey) — plants due next month.
  4. Later this year — collapsed section, expandable.
• Each entry: plant name, location, recommended months, last pruned date. Tap to open plant detail.
• Month strip at top (scrollable) to jump to any month and see what's scheduled.

Species Detail (/species/<id>/) — optional read-only

• Shows all species info as reference. Linked from plant detail. Not editable directly (edit via the plant form).

---

5. Perenual API Integration

• Endpoint used: GET https://perenual.com/api/species-list?q=<name>&key=<API_KEY>
• API key: stored in Django settings via environment variable PERENUAL_API_KEY.
• Cache strategy: on first successful lookup, a Species row is created with perenual_id set. Any subsequent search that returns a species already in the DB skips the API entirely.
• Free tier limit: 100 requests/day. Given that lookups only happen when adding new plants (not on every page view), this is not a practical constraint for a family app.
• Fallback: if the API is unreachable or returns an error, the add-plant form stays open with an empty species form for manual entry. No hard dependency on the API.

---

6. Pruning Logic

A plant is considered overdue for pruning if:

• It has at least one pruning_month that fell within the past 12 months, AND
• There is no PruningLog entry with pruned_on falling within that month's window.

A plant is due this month if the current month is in Plant.pruning_months and not yet logged this month.

Using a 12-month rolling window (rather than calendar-year) correctly handles plants due in December when checked in January.

The pruning calendar view computes this in a Django queryset annotated with the current date — no background tasks or scheduled jobs needed.

---

7. Deployment

Docker Compose

services:
  web:      Django + Gunicorn
  nginx:    Reverse proxy + static/media serving

volumes:
  db:       SQLite file
  media:    Uploaded plant photos

• Accessible on the local network via homelab IP or a local hostname (e.g. plantdb.home).
• No SSL required for LAN use.
• docker compose up -d starts everything; docker compose down stops it.
• Database backup: copy the SQLite volume file. Simple enough to add to an existing homelab backup routine.

Environment Variables

Variable	Purpose
PERENUAL_API_KEY	Perenual API key
SECRET_KEY	Django secret key
DEBUG	False in production
ALLOWED_HOSTS	Homelab hostname/IP

---

8. Static & Media Files

• Static files (CSS, JS, Bootstrap): collected via manage.py collectstatic, served by Nginx.
• Media files (plant photos): stored in /media/ inside the container, mounted as a Docker volume, served by Nginx under /media/.

---

9. Dependencies

Package	Purpose
django	Web framework
gunicorn	WSGI server
django-htmx	HTMX integration helpers
pillow	Image handling for ImageField
requests	Perenual API calls

No frontend build step — Bootstrap 5 and HTMX loaded via CDN or bundled as static files.

---

10. Out of Scope

• User authentication / accounts
• Watering or feeding reminders
• Push notifications
• Multi-language support
• Public internet access / SSL (LAN only)
• Offline / PWA mode