An offline-first plant & leaf health journal with secure Google Gemini AI analysis. Photograph a leaf, get high-accuracy plant health assessments powered by Google Gemini API via a lightweight Node.js Express backend, review cautious observations with actionable care guidance, and manage your daily plant-care streak — with full offline journal capabilities when away from signal.
GEMINI_API_KEY stays strictly on the server and is never exposed to the client or browser bundles. Photos are only transmitted when you explicitly tap “Analyse with Gemini AI”. No GPS coordinates or unrelated journal data are sent to AI.gemini (production default via Express), demo (deterministic mock for CI/E2E), and transformersjs (legacy on-device SmolVLM).getUserMedia) or photo picker, preview & retake, client-side resizing & compression, optional observation note, secure Gemini analysis with multi-step progress and cancel, structured result, save (photo and location optional) or save without analysis.cd server
cp .env.example .env
# Edit server/.env and provide your GEMINI_API_KEY from Google AI Studio
# Default model: gemini-3.8-flash (or gemini-2.0-flash)
npm install
npm run dev # Starts Express backend on http://localhost:3001
In a separate terminal from project root:
npm install
cp .env.example .env # Optional (defaults connect to http://localhost:3001/api)
npm run dev # Starts Vite frontend on http://localhost:5173
Open http://localhost:5173, complete onboarding, and start journaling or scanning leaves!
The service worker is only active in production builds. To test PWA/offline behaviour:
npm run build && npm run preview→ http://localhost:4173
| Command | Purpose |
|---|---|
npm run dev |
Development Vite frontend server (http://localhost:5173) |
npm run build |
Type-check + production build into dist/ |
npm run preview |
Serve the production build locally |
npm run lint / npm run typecheck |
ESLint / TypeScript checking for frontend |
npm test |
Unit + component tests (Vitest) |
npm run check |
Run full lint + typecheck + test + build pipeline |
npm run server:dev |
Start Express backend in watch mode (http://localhost:3001) |
npm run server:build |
Compile Express backend TypeScript to server/dist/ |
npm run server:start |
Run compiled Express backend in production mode |
npm run server:typecheck |
Type-check server code (tsc --noEmit) |
npm run server:test |
Run server unit & API route tests (Vitest) |
npm run test:e2e |
Playwright E2E tests |
npm run icons |
Regenerate PWA icons |
Details: docs/TESTING.md.
VITE_*). Stored in root .env. Never put API keys here.server/.env (git-ignored). Contains GEMINI_API_KEY, GEMINI_MODEL, PORT, and CLIENT_ORIGIN.
See docs/ENVIRONMENT.md.gemini): Routes requests to Google Gemini multimodal vision models (gemini-3.8-flash, gemini-2.0-flash) via the Express backend. Delivers fast, accurate plant health analysis with structured schema extraction while protecting device battery and RAM.demo): Deterministic mock provider for automated tests, offline development, and CI environments without network dependencies.transformersjs): On-device SmolVLM-500M / SmolVLM-256M running via Transformers.js and ONNX Web Worker (available as an optional fallback).Read docs/AI_MODEL.md and docs/AI_PROMPTS.md.
Works offline after the first visit: every screen, your data, care tracking, export/import, and AI analysis if the model download finished. Needs internet: first visit, model download, map tiles, app updates. Browsers can evict storage under pressure; the app re-checks and tells you. See docs/OFFLINE_PWA.md.
OpenStreetMap tiles by default (attribution always shown; subject to the OSMF tile usage policy). Location is only requested when you press a location button. No offline basemap. See docs/MAPS_AND_GEOLOCATION.md.
Static hosting — Cloudflare Pages recommended (build npm run build, output dist); GitHub Pages
supported with VITE_BASE_PATH. See docs/DEPLOYMENT.md.
docs/README.md indexes everything: requirements, architecture (with diagram), AI model and prompts, database schema, offline/PWA, maps, environment, security & privacy, UI/UX, testing, deployment, troubleshooting, roadmap and ADRs.
MIT (see LICENSE); third-party models, components and fixtures keep their own licences.
See docs/IMPLEMENTATION_REPORT.md for measured results and incomplete requirements. The shared data model is documented in ASSESSMENT_SCHEMA.md and DATABASE_SCHEMA.md. Plant timelines retain assessment history and compare deterministic symptom sets.
Netlify is supported: root netlify.toml builds with npm run build and publishes dist with an SPA rewrite. All environment values are optional public build-time settings, listed in .env.example. No secrets or AI keys are needed. Production guide includes every supported variable, Netlify steps, Cloudflare Pages fallback and post-deploy checks.