An AI-powered web application to support and simplify everyday gardening.
GardenAssist helps gardeners keep track of their plants, plan garden tasks, and get intelligent advice — all in one place. An integrated AI assistant can answer questions, explain care instructions, identify plants, and help manage your garden data through natural conversation.
Maintain a comprehensive list of all plants in your garden. Each plant includes care details such as pruning schedules, fertilization cycles, bloom periods, leaf and flower colors, frost tolerance, and general growing conditions. Track the current state and age of each plant, as well as the dates of last care activities.
View all open, current, and upcoming garden tasks at a glance. Mark tasks as done or skip them as needed. A monthly calendar overview provides a quick visual indication of which months have pending work, with details available on hover.
A Gantt-style calendar with plants as rows and months as columns gives a seasonal overview of bloom times, pruning windows, fertilization periods, and growth phases — with color-coded display per activity type.
An interactive layout of your garden showing the position and size of each plant. Hover over plant symbols to see a quick summary; click to open the full plant detail view. Selecting a plant in the table highlights its location in the plan.
A conversational assistant that supports you throughout the app:
- Answer questions about plants, care routines, and gardening best practices
- Explain why a task is recommended at a given time
- Add or update plant data as well as journal entries through natural language
Track fertilizers, pesticides, soil amendments, and other garden products. Each item stores photos, category, storage location, use-case description, EAN barcode, active ingredients with percentages, application directions, dosage, and free-form notes. The list is searchable and filterable by category. The AI assistant is always aware of the full inventory and can recommend products or answer questions in context.
A diary for logging completed tasks, observations, and notes over time. Provides a personal history of your garden's development.
A central overview combining urgent hints and warnings, open and upcoming tasks, the garden plan, a monthly task band, and the AI chat window — everything relevant at a single glance.
Dashboard — weather widget, open tasks with done/skip actions, interactive garden plan with plant markers, and the monthly task band. |
AI Assistant — the assistant panel opens alongside any view. Here it answers a question about fertilizing the apple tree, citing the plant's own schedule. |
Plant list & detail — sortable table with bloom, health, and task columns; clicking a row opens the detail panel with photos, facts, care notes, and schedule history. |
Garden calendar — Gantt-style view with plants as rows and months as columns. Filter by activity type (bloom, growth, foliage, fertilization, pruning, misc). |
Garden journal — chronological log of completed tasks, skipped items, observations, and problems. Filterable by entry type. |
AI-assisted plant entry — asking the assistant to add a yellow rose automatically opens the plant form pre-filled with name, description, category, care notes, and bloom schedules. Information provided by the assistant is always marked orange and can individually deselected or overwritten. The user always needs to save to accept changes suggested by the assistant. Journal entries can also be added, modified, or deleted using the assistant. |
Supplies inventory — searchable, filterable list of fertilizers, pesticides, and other garden products with category tags, storage location, and use-case descriptions. The AI assistant has full inventory context and can answer questions like "how many supplies do I have?" or recommend the right product for a task. |
Supply detail — clicking a product opens a detail panel with photos, use-case description, properties (EAN, location), a full ingredients table with percentages, application directions, dosage, and notes. The AI assistant context updates to the selected product so questions like "when should I apply this?" are answered in context. |
Tasks — overdue and current tasks grouped by urgency, with done/skip actions and weather widget. |
Plants — scrollable plant list with photo thumbnails, location tags, and next task status. |
Garden plan & plant detail — interactive map with plant markers; tapping a marker slides up a detail sheet with photos and care notes. |
Calendar — Gantt-style seasonal overview, filterable by activity type. |
Journal — chronological task log with done/skipped/observation entries, filterable by type. |
Supplies — inventory list with category tags and storage location. |
AI Assistant — snap-sheet chat panel slides up from the bottom, available in every view. |
- Event API API to add watering events, e.g., based on home assistant automations
- User authentication based on OpenID Connect
- Photo analysis Identify plants from uploaded photos, search for suitable reference images, or analyze uploaded documents or photos for relevant gardening context
- Calendar sync – export or sync garden tasks to external calendar apps
- Email notifications – reminders for upcoming or overdue tasks
| Component | Technology | Rationale |
|---|---|---|
| Framework | React + TypeScript | Industry standard; best AI code generation support |
| Build tool | Vite | Fast dev server and build; replaces Create React App |
| UI components | shadcn/ui | Radix UI (accessible, headless) + Tailwind; components copied into project for full control |
| Styling | Tailwind CSS | Utility-first; no separate CSS files needed |
| Component | Technology | Rationale |
|---|---|---|
| Server framework | Hono | Lightweight, TypeScript-first; simpler than NestJS, more modern than Express |
| Validation | Zod | Runtime validation of all API inputs; enables OpenAPI generation for future mobile client (see ADR-007) |
| ORM | Drizzle | TypeScript-first schema definition; lightweight; supports SQLite and PostgreSQL with a single connection config change |
| Database | SQLite (v1) → PostgreSQL (future) | SQLite for zero-dependency on-premise install; Drizzle abstracts the switch to PostgreSQL |
| Component | Technology | Rationale |
|---|---|---|
| Containerization | Docker | On-premise, self-hostable; single docker-compose.yml for the full stack |
| Persistence | Docker Volume | SQLite file and attachment directory mounted as a volume; survives container restarts |
- Node.js >= 20
- pnpm >= 9 — install with
npm install -g pnpm - Docker + Docker Compose (for production deployment)
pnpm install# Frontend (React + Vite, http://localhost:5173)
pnpm dev:frontend
# Backend (Hono, http://localhost:3000)
pnpm dev:backendAPI requests from the frontend are proxied to the backend via Vite's dev proxy
(/api → http://localhost:3000).
pnpm typecheckNo local build required. Images are published automatically on every push to main
and on every version tag (v*.*.*).
# 1. Copy and adjust environment variables
cp .env.example .env # set GARDENASSIST_PORT if needed
# 2. Pull the latest images and start the stack
docker compose -f docker-compose.prod.yml pull
docker compose -f docker-compose.prod.yml up -dThe frontend is reachable at http://<server>:3110 (or the port set via GARDENASSIST_PORT).
To pin a specific version instead of latest, edit docker-compose.prod.yml and replace
:latest with the desired tag, e.g. :1.2.0.
To update to a newer version:
docker compose -f docker-compose.prod.yml pull
docker compose -f docker-compose.prod.yml up -dData (SQLite database + attachments) is persisted in the named Docker volume gardenassist_data
and survives container restarts and image updates.
# Copy and adjust environment variables
cp .env.example .env
# Build images locally and start the stack
docker compose up --buildTo use PostgreSQL instead of SQLite, set DATABASE_URL in .env:
DATABASE_URL=postgresql://user:password@host:5432/gardenassist
If a reverse proxy (e.g. Nginx, Traefik, Caddy) sits in front of the GardenAssist frontend container, it must allow large request bodies for the import endpoints — otherwise the proxy rejects the request with a 413 before it reaches the container. Apply an equivalent body size limit (512 MB or more) for the following paths:
POST /api/import/backup— full backup restore (tar.gz, DB + attachments)POST /api/import/json— JSON data import
The frontend container's built-in nginx already applies client_max_body_size 512m
for both paths; only the upstream proxy requires explicit configuration.
All variables are optional unless marked required.
| Variable | Default | Description |
|---|---|---|
GARDENASSIST_PORT |
3110 |
Host port the frontend is exposed on |
GARDENASSIST_VERSION |
latest |
Image tag to pull from ghcr.io (e.g. 1.2.0) |
These variables are forwarded from the host environment to the backend container via docker-compose.yml / docker-compose.prod.yml.
| Variable | Default | Description |
|---|---|---|
DATABASE_URL |
file:/data/gardenassist.db |
SQLite file path or PostgreSQL connection string |
DATA_DIR |
/data |
Directory for uploaded attachments and static files |
PORT |
3000 |
Internal port the backend listens on |
AI_PROVIDER |
(empty) | AI provider: anthropic, openai, or openrouter |
AI_MODEL |
(empty) | Model ID, e.g. claude-sonnet-4-6, gpt-4o, or an OpenRouter model string |
AI_API_KEY |
(empty) | API key for the selected provider |
AI variable behaviour: The three AI variables are used as fallbacks when the corresponding fields in the Settings UI are empty. A value entered via the UI (stored in the database) always takes precedence. Clearing the UI value restores the env var fallback. This lets you pre-configure the assistant for a deployment without requiring each user to enter credentials manually.
The TypeScript types in docs/api/ are the source of truth for the data model.
Both packages import them via the @api/* path alias, e.g.:
import type { Garden } from "@api/garden";No copying or code generation required — the alias resolves directly to docs/api/.
🌱 Development — core features implemented and in use.
| Feature | Status |
|---|---|
| Plant management (list, detail, edit, attachments) | ✅ Done |
| Dashboard (task list, warnings, garden plan, weather widget) | ✅ Done |
| Garden calendar (Gantt, color presets) | ✅ Done |
| Journal (timeline, filters, manual entries, done/skipped tasks) | ✅ Done |
| Supplies inventory (list, detail, ingredients, photos) | ✅ Done |
| Settings (all sections, API integration, language switch) | ✅ Done |
| Garden plan upload | ✅ Done |
| AI Assistant (provider-agnostic, persistent across views) | ✅ Done |
| Export / Import (JSON, backup tar.gz) | ✅ Done |
| Weather widget (Open-Meteo, real-time, 5-day forecast) | ✅ Done |
| Docker build + ghcr.io publish (GitHub Actions) | ✅ Done |
| Mobile view (all views, AI assistant, responsive layout) | ✅ Done |
| Soil moisture / water balance (Open-Meteo Archive) | ✅ Done |
| CSV export | 🔲 Ready |