# PlantStack — Complete Technical Dossier & AI Reference Manual > Canonical URL: https://plantstack.it/ > Project Author: Jan Schneidt (sm4sh.it) > GitHub: https://github.com/sm4sh-it/PlantStack > Docker Image: ghcr.io/sm4sh-it/plantstack:latest > License: PolyForm Noncommercial 1.0.0 --- ## 1. Executive Summary & Purpose PlantStack is a modern, minimalist, resource-efficient plant care management web application designed specifically for self-hosters and houseplant enthusiasts. In contrast to commercial proprietary apps (such as Planta, PictureThis, or Greg), PlantStack offers: 1. **100% Data Sovereignty**: All plant records, historical logs, and uploaded images remain entirely on the user's private local hardware. 2. **Zero Cloud Subscriptions**: No paywalls, no recurring costs, no mandatory user accounts, and no data tracking. 3. **Botanical Modernism UX**: A high-aesthetic UI built with Next.js 15, React 19, and Tailwind CSS following the Anti-Outline standard (soft-tint surfaces, organic card elevation, and 44px touch targets). 4. **Vibe Coded & Rigorously Audited**: Developed through agile AI pair-programming with Google Gemini via the Antigravity CLI, combining rapid feature velocity with disciplined security audits (OWASP Top 10 / CWE). --- ## 2. Core Features & Functional Details ### 2.1 4-in-1 Routine Care & Milestones PlantStack tracks four routine maintenance actions: - 💧 **Watering**: Configurable base intervals with seasonal adaptive math. - âœĻ **Fertilizing**: Granular schedules with automated pause during winter dormancy. - 🐛 **Pest Combat**: Dedicated tracking for infestation treatments (e.g., Neem oil, predatory mites, insecticidal soap). - ðŸ›Ąïļ **Fungus Protection**: Record preventative or therapeutic antifungal applications. In addition to routine care, PlantStack features dedicated milestone buttons: - ðŸŠī **Repotting**: Records date, new pot size, and soil mixture. - ✂ïļ **Pruning**: Records seasonal trim dates and shaping notes. **Permanent Milestone Retention**: Pruning and repotting dates are stored as permanent timestamps directly on the `Plant` entity (`lastPruned`, `lastRepotted`) in addition to chronological `PlantEvent` logs. This ensures that pruning and repotting histories are never erased or displaced by frequent watering entries, even if routine care history is cleared. ### 2.2 4-Tier Gentle Urgency Sorting Rather than imposing rigid calendar dates that induce guilt or stress, PlantStack computes urgency dynamically and sorts plants into 4 visual tiers: 1. ðŸ”ī **Overdue**: Care interval exceeded. 2. ðŸŸĄ **Due Today**: Scheduled for attention today. 3. ðŸ”ĩ **Due Soon**: Upcoming in the next 1–2 days. 4. ðŸŸĒ **In Schedule**: Adequately hydrated and nourished. Features include: - **1-Click Batch Watering**: Waters all currently due plants with a single confirmation. - **Snooze (+2 Days)**: Defers care when soil is still damp without corrupting historical intervals. - **Instant Undo**: Floating toasts allow reverting accidental taps immediately. ### 2.3 Winter Dormancy Switch Overwatering during winter is the leading cause of houseplant root rot in temperate climates. PlantStack provides an intuitive dormancy switch in settings: - **Switch Activation**: Simple manual toggle in settings. - **Watering Adjustment**: Automatically stretches all watering intervals by +50%. - **Fertilizer Pause**: Safely postpones fertilization schedules until spring daylight returns. ### 2.4 Locations: Indoor & Outdoor (Balcony) Structure your collection by physical living environments: - **Custom Habitats**: Living room, bedroom, shaded windowsills, or sunny outdoor balcony. - **Contextual Lighting**: Assign light profiles (direct sun, bright indirect, partial shade, low light). - **Zoned Overview**: Filter and manage care by specific rooms or balcony zones. ### 2.5 Weather Sync & Frost Alerts via Open-Meteo PlantStack integrates with the open-source Open-Meteo API using latitude and longitude coordinates stored in application config: - **Rain Tracking**: Measures local precipitation to adjust outdoor plant watering needs. - **Frost Warning Engine**: Automatically detects sub-zero temperature forecasts and issues outdoor plant frost alerts on the dashboard. ### 2.6 Botanical Intelligence (Open Plantbook) Integrated with Open Plantbook (open.plantbook.io): - As-you-type botanical autocomplete without layout shifts (Zero-CLS). - Auto-populates scientific nomenclature, native geographical origin, recommended sunlight tiers, and soil humidity preferences. ### 2.7 Growth Photo Diary & Historical Logs - **Multi-Photo Timeline**: Upload high-resolution photos documenting growth milestones, flowering, or repotting. - **Inspection Lightbox**: Fullscreen zoom modal with timestamp and notes. - **Collapsible Event Log**: Paginated chronological history for every plant. ### 2.8 Plant Archive & Chronic - **Safe Archiving**: Relocated, gifted, or deceased plants can be archived with a single click. - **Preserved History**: All historical photos, notes, and care metrics remain permanently queryable without cluttering the active dashboard. ### 2.9 Gamification & Interactive Statistics - **44 Collectable Enamel Pins**: 8 progression chains (Rainmaker, Botany Nerd, World Tour, Rooms, Repot Master, Master Gardener, Methuselah, Species Diversity). - **Interactive Statistics**: Recharts-powered graphs analyzing watering frequencies, care streaks, and collection health scores over time. ### 2.10 1-Click Backup & Data Portability - **ZIP Export**: Generates a single compressed archive containing the complete SQLite database and all uploaded original photos. - **ZIP Import**: Restores full database state with path-traversal (Zip-Slip) protection and zip-bomb validation. --- ## 3. Architecture, Security & Docker Deployment ### 3.1 Vibe Coded with Gemini & Rigorously Audited PlantStack is vibe-coded in pair-programming with Google Gemini (via the Antigravity CLI) — embracing rapid iteration, modern React 19 / Next.js 15 paradigms, and high feature velocity. Rapid prototyping is matched with rigorous software discipline: - ðŸ›Ąïļ **Comprehensive Security Audits**: Structured CWE reviews covering OWASP Top 10 vulnerabilities. - 🔒 **Defense-in-Depth**: Strict binary magic-byte verification for image uploads, zip-bomb & path-traversal mitigation for backups, and CSRF protection. - ðŸ“Ą **Smart Home Ready**: Dedicated status API (`GET /api/plants/status`) for Home Assistant, ESPHome e-ink bedside displays, or MagicMirrors. ### 3.2 Dual-Auth Gate & Security - **Open LAN Mode (Default)**: If `PLANTSTACK_API_SECRET` is unset, the UI requires no login credentials on a trusted home network. - **Protected Mode**: When `PLANTSTACK_API_SECRET` is defined, a botanical lockscreen guards all views and issues secure 30-day session cookies. --- ## 4. Frequently Asked Questions (FAQ) ### Q: What hardware is required to run PlantStack? A: PlantStack is extremely lightweight. It runs comfortably on a Raspberry Pi 3/4/5, any Synology/QNAP NAS with Docker capability, Unraid, TrueNAS SCALE, or any Linux VPS with at least 512MB of available RAM. ### Q: Does PlantStack send my photos or plant data to the cloud? A: No. All plant data, photos, care logs, and notes are stored locally in the mounted `/app/data` volume. Only weather queries (Open-Meteo) and species lookups (Open Plantbook, optional) establish outgoing HTTP requests. ### Q: How does the Winter Dormancy mode work? A: You enable winter dormancy with a simple toggle switch in settings. PlantStack automatically stretches watering intervals by 50% and safely pauses fertilizing routines until spring. ### Q: What does it mean that PlantStack is vibe-coded? A: PlantStack is continuously developed in agile AI pair-programming with Google Gemini through the Antigravity CLI. This approach combines lightning-fast feature releases and modern web paradigms with thorough security audits and robust engineering.