Demeter — Features and Capabilities

Demeter is the Greek goddess of the harvest, grain, and fertile earth — the embodiment of agriculture and the cycles of growth that sustain life. The Demeter domain is a comprehensive home gardening and small-scale agriculture platform built on fourteen TypeScript libraries plus three applications — a Fastify REST API (@demeter/api), a React web app (@demeter/web), and a React Native/Expo mobile app (@demeter/mobile). It covers: a botanical plant encyclopedia with companion planting and pest management intelligence; three complementary climate zone systems (USDA Hardiness, Koppen, AHS Heat Zones); IoT sensor networks for soil and atmospheric monitoring over MQTT, Zigbee, BLE, and LoRa protocols; automated irrigation and greenhouse climate control; a canvas-based garden layout planner with solar analysis and square-foot spacing; hydroponic system management for seven system types with full nutrient chemistry; aquaponics, indoor growing, microgreens, and mushroom cultivation; seed and supply inventory with viability and seed-saving support; post-harvest food preservation following USDA/NCHFP guidelines (canning, freezing, dehydrating, fermenting, root cellar); community gardening with seed exchanges, expert Q&A, and group management; agricultural analytics and ROI tracking; and AI-powered plant identification, disease diagnosis, and natural language garden advisory.

Demeter is organized into 14 TypeScript libraries, each owning a distinct capability area. The sections below cover each library in turn, followed by the data foundation that underpins all of them and the three applications that expose the platform to end users.

Table of Contents#

1. Plant Encyclopedia and Knowledge Base (@demeter/plants)
2. Companion Planting Intelligence
3. Pest and Disease Management
4. Climate Zone System
5. Seasonal Calendar and Planning
6. Plant Search and Discovery
7. Weather Integration (@demeter/weather)
8. IoT Sensor Network (@demeter/sensors)
9. Garden Automation (@demeter/automation)
10. Garden Planning and Design (@demeter/planner)
11. Crop Rotation and Succession Planting
12. Hydroponic Systems (@demeter/hydroponics)
13. Aquaponics
14. Indoor Growing and Controlled Environment
15. Microgreens Production
16. Mushroom Cultivation
17. Seed and Supply Inventory (@demeter/inventory)
18. Garden Journaling (@demeter/journal)
19. Post-Harvest Preservation (@demeter/preservation)
20. Task and Schedule Management (@demeter/tasks)
21. Community Gardening Platform (@demeter/community)
22. Agricultural Analytics (@demeter/analytics)
23. AI-Powered Agricultural Intelligence (@demeter/intelligence)
24. Data Foundation (@demeter/core)
25. Applications (API, Web, Mobile)
26. Domain Boundaries

1. Plant Encyclopedia and Knowledge Base#

Package: @demeter/plants

1.1 Species Data Models#

Each plant species in the encyclopedia carries a full botanical record:

• Complete species profiles — Taxonomy (family, genus, species), growing requirements, planting instructions, care guides, harvest timing, and nutritional content.
• Variety tracking — Multiple cultivar varieties per species with distinct growing characteristics, disease resistance ratings, flavor profiles, and days-to-maturity.
• Taxonomic classification — Formal taxonomic hierarchy for accurate plant identification and grouping (e.g., tomatoes as Solanum lycopersicum in the Solanaceae family, enabling family-level companion planting and rotation planning).
• Growing requirements — Sun (full sun / partial sun / partial shade / full shade), water needs, soil pH range, soil type, temperature range (min/max), spacing requirements, and planting depth.
• Planting instructions — Step-by-step guidance covering direct sow, transplant, container, and raised bed methods.
• Care guides — Watering frequency, fertilization schedule, pruning technique, staking requirements, and mulching recommendations.
• Harvest information — When to harvest by visual and tactile indicators, how to harvest without damaging the plant, expected yield per plant or row, and post-harvest storage recommendations.
• Nutritional data — Per-serving nutritional profiles for edible plants: vitamins, minerals, and macronutrients.
• Culinary and medicinal uses — Cooking applications, flavor profiles, preparation methods, and documented traditional medicinal properties.

1.2 Pre-Built Plant Databases#

Four specialized databases are pre-populated with validated data:

• Vegetable database — Comprehensive vegetable profiles organized by botanical family and growing season.
• Herb database — Culinary and medicinal herbs with growing conditions, harvest methods, and preservation guidance.
• Fruit database — Fruit trees, bushes, and vines with pollination requirements, chill hour needs, and yield expectations. Chill hours are the hours below 45°F (7°C) that many fruit trees require during winter dormancy to produce fruit the following spring — without sufficient chill hours, a fruit tree may bloom poorly or not at all.
• Flower database — Ornamentals categorized by bloom time, color, height, and pollinator attraction.

2. Companion Planting Intelligence#

2.1 Companion Relationships#

Companion planting is the practice of growing different plants near each other for mutual benefit. The relationships are based on documented biological mechanisms, not folklore.

• Companion database — Complete database of plant companion relationships with documented interaction mechanisms.
• Beneficial pairings — Plants that actively help each other:
  • Nitrogen fixation — Legumes (beans, peas) fix atmospheric nitrogen into the soil, benefiting neighboring heavy feeders like corn or squash.
  • Trap cropping — A sacrificial plant that attracts pests away from the main crop (e.g., nasturtiums attracting aphids away from vegetables).
  • Pest deterrence — Strong-scented plants (basil, marigolds) repel specific insects.
  • Shade provision — Tall plants providing beneficial shade to heat-sensitive neighbors.
• Detrimental pairings — Plants that inhibit each other:
  • Allelopathy — Plants that release chemicals suppressing nearby plant growth (e.g., black walnut releasing juglone).
  • Competition — Plants competing for the same root space or nutrients.
  • Disease transmission — Plants that can share pathogens.
• Relationship scoring — Numeric compatibility scores for any pairing based on multiple interaction factors.
• Mechanism documentation — Scientific explanation of each companion relationship.

2.2 Advanced Companion Planning#

• Guild planting — Automated suggestions for plant guilds: self- supporting groups of mutually beneficial plants organized around a central species. A classic guild: a fruit tree, nitrogen-fixing shrubs, ground cover, and aromatic pest deterrents.
• Three Sisters layout — Pre-built layout generation for the traditional Native American corn-beans-squash companion system. Corn provides a pole for beans; beans fix nitrogen; squash shades the soil, reducing weeds and water loss.
• Bed compatibility analysis — Whole-bed analysis checking all pairwise plant interactions within a garden bed.
• Companion chart — Visual matrix showing all relationships between selected plants as a color-coded grid.

3. Pest and Disease Management#

3.1 Identification and Diagnosis#

• Pest database — Comprehensive catalog of common garden pests with identification photos, characteristic damage symptoms, and host plants.
• Disease database — Plant disease reference covering bacterial, fungal, viral, and physiological conditions.
• Beneficial insect catalog — Catalog of predatory and parasitic insects (ladybugs, lacewings, parasitic wasps) with the pests they control and how to attract them.
• Symptom-based identification — Identify likely pests or diseases from observed damage patterns (e.g., "small holes in leaf margins, silvery streaks" → flea beetles).
• Treatment recommendations — Multi-option treatment plans ranked from least to most intervention: cultural controls → biological controls → organic treatments → conventional treatments.

3.2 Integrated Pest Management (IPM)#

IPM is an evidence-based approach that uses the least disruptive effective method, starting with prevention and biological controls before reaching for pesticides. It is the USDA-recommended approach for sustainable pest management.

• IPM plan generation — Automated IPM plans based on garden conditions and current pest pressure.
• Prevention strategies — Crop rotation, companion planting, row covers, and physical barriers as first-line defenses.
• Biological control guidance — Using beneficial insects, nematodes, and microbial insecticides (Bt) to control pest populations naturally.
• Action thresholds — Pest population tracking against economic or aesthetic action thresholds — the population level at which intervention is warranted. Not every pest sighting requires treatment.

4. Climate Zone System#

4.1 Zone Classification#

Three complementary zone classification systems are supported:

• USDA Hardiness Zones — The standard US planting zone map (zones 1a through 13b) based on average annual minimum temperature. Zone 5a withstands -20°F; zone 9a withstands 20°F. Used to determine which perennial plants can survive winter in a given location.
• Koppen Climate Classification — The global climate classification system (tropical, arid, temperate, continental, polar) mapping regional climate types to growing conditions and crop suitability.
• AHS Heat Zones — The American Horticultural Society Heat Zone Map counts the number of "heat days" (above 86°F/30°C) per year. Many plants suffer heat stress even if they survive cold temperatures.
• Frost date database — State-by-state last spring frost and first fall frost dates for calculating planting windows.

4.2 Climate Calculations#

• Growing season length — Automatic calculation of growing season duration from frost date data.
• Growing degree days (GDD) — Accumulated heat units tracking for predicting plant development stages and harvest dates. GDD is calculated by averaging the daily high and low temperatures and subtracting a base temperature. Corn requires ~2700 GDD from planting to maturity.
• Chill hours — Chill hour accumulation for fruit trees and perennials requiring winter dormancy. Insufficient chill hours result in poor spring flowering and fruiting.
• Hardiness checking — Automatic plant-to-zone compatibility verification.
• Zone-based filtering — Filter the entire plant database to show only species suitable for a given hardiness zone.
• Microclimate estimation — Account for elevation, urban heat islands (cities are typically 2–9°F warmer), wind exposure, and water proximity when determining local growing conditions.

5. Seasonal Calendar and Planning#

5.1 Planting Calendars#

• Zone-customized calendars — Planting calendars with indoor start dates, direct sow dates, and transplant dates customized to local hardiness zone and frost dates.
• Seed start schedules — Indoor seed starting schedules calculated backward from transplant dates with light and temperature requirements for each stage.
• Transplant schedules — Outdoor transplant timing based on frost dates, soil temperature, and hardening-off completion.
• Succession schedules — Staggered planting schedules for continuous harvest throughout the growing season. Rather than planting all lettuce on the same day (resulting in a simultaneous glut), succession planting staggers sowings 2–3 weeks apart for a rolling harvest.
• Fall planting calendars — Reverse-calculated fall planting dates for second-season crops and overwintering varieties.
• Monthly task lists — Month-by-month gardening task lists customized to zone and garden contents.

5.2 Moon Phase Gardening#

Traditional lunar gardening correlates planting activities with the moon's cycle, based on centuries-old agricultural traditions (and some modern biodynamic research, though scientific evidence remains mixed).

• Moon phase calculation — Accurate moon phase calculation (new, waxing crescent, first quarter, waxing gibbous, full, waning gibbous, last quarter, waning crescent) for any date.
• Moon planting guidance — Traditional lunar guidance: plant above-ground crops during waxing phase, root crops during waning phase, avoid planting during new and full moon.
• Printable calendar — Exportable calendar combining planting dates, moon phases, and task reminders.

6. Plant Search and Discovery#

6.1 Search Capabilities#

• Fuzzy name search — Find plants even with misspelled or partial names.
• Faceted search — Multi-facet filtering: plant type, sun needs, water needs, hardiness zone, botanical family.
• Full-text search — Combined search across plant names, descriptions, growing notes, and culinary uses.
• Nutrition-based search — Find plants by nutritional content (high vitamin C, high iron, high protein).

6.2 Plant Recommendations#

• Similar plant suggestions — Find plants similar to a selected species based on growing conditions and botanical family.
• Beginner suggestions — Curated easy-to-grow recommendations for new gardeners.
• Pollinator plant suggestions — Plants that attract bees, butterflies, and other pollinators.
• Edible landscaping suggestions — Attractive edible plants serving both ornamental and food production purposes.
• Problem-solver suggestions — Plants recommended for specific challenges (drought-tolerant, shade-loving, deer-resistant).
• Harvest-time suggestions — Find plants by desired harvest window to fill gaps in seasonal food production.

7. Weather Integration#

Package: @demeter/weather

7.1 Data and Conditions#

• Multi-source data adapters — Weather data integration from multiple weather service providers with a unified data format regardless of source.
• Current conditions analysis — Real-time weather condition assessment with relevance to garden activities.
• Forecast integration — Multi-day weather forecasting integrated with garden planning and task scheduling.
• Historical data — Historical weather data access for trend analysis and season comparison.

7.2 Garden-Specific Weather Alerts#

• Frost warning alerts — Notifications when temperatures approach frost thresholds for tender plants, with enough lead time to take protective action.
• Heat stress warnings — Alerts for heat waves affecting sensitive crops.
• High-wind alerts — Staking and protection recommendations when wind speeds are forecast.
• GDD tracking integration — Automatic GDD accumulation from weather data for crop maturity prediction.
• Rainfall tracking — Rainfall measurement integration for irrigation scheduling (no need to water if there was significant rain).

8. IoT Sensor Network#

Package: @demeter/sensors

8.1 Device Management#

• Device registration — Register and manage garden sensor devices with unique identifiers, installation location, and metadata.
• Device discovery — Automatic discovery of compatible sensors on the local network.
• Lifecycle management — Complete device lifecycle from provisioning through decommission, including maintenance and battery status.

8.2 Protocol Support#

Four wireless protocols cover different distance and power requirements:

8.3 Sensor Types and Analytics#

Supported sensor types: soil moisture, soil temperature, air temperature, humidity, light level (lux/PAR), pH, and EC (electrical conductivity).

• Reading collection — Sensor data collection with validation, normalization, and unit conversion.
• Time-series analytics — Aggregation (hourly, daily, weekly) and trend analysis.
• Anomaly detection — Automatic identification of unusual readings indicating equipment malfunction or extreme conditions.
• Sensor calibration — Calibration workflow management with drift correction and accuracy verification.
• Commercial integrations — Pre-built adapters for popular commercial garden monitoring platforms.

9. Garden Automation#

Package: @demeter/automation

9.1 Rules Engine#

• Condition-action rules — Define automation rules: "If soil moisture drops below 30%, activate zone 2 irrigation for 15 minutes."
• Multi-condition triggers — Compound triggers combining sensor thresholds, time schedules, and weather forecasts (AND/OR logic).
• Action execution — Automated irrigation, ventilation, heating, cooling, and notifications.
• Rule scheduling — Time-based rule activation with recurring schedules and seasonal adjustments.

9.2 Irrigation Control#

• Smart scheduling — Weather-adjusted irrigation that accounts for recent rainfall and forecast rain — if 0.5" of rain is forecast today, skip the scheduled watering.
• Zone control — Multi-zone irrigation management with independent schedules per garden area.
• Moisture-based activation — Sensor-driven irrigation that waters only when soil moisture drops below configured thresholds — far more efficient than schedule-only systems.
• Water usage tracking — Total water consumption monitoring with historical comparisons.

9.3 Greenhouse Climate Control#

• Temperature regulation — Automated heating and cooling based on temperature setpoints.
• Humidity control — Humidity monitoring and regulation through ventilation and misting system control.
• Ventilation management — Automatic vent opening and fan control based on temperature and humidity readings.

9.4 Scenes and Alerts#

• Predefined scenes — Pre-built automation bundles: nighttime frost protection (activate heat mats, close vents), morning watering (zone-based irrigation), greenhouse ventilation (temperature-triggered fans).
• Custom scenes — User-defined automation bundles grouping multiple actions into single-trigger scenarios.
• Critical condition alerts — Automated notifications for frost warnings, extreme heat, dangerously dry soil, and pest detections.
• Automation history — Complete audit log of all automated actions.

10. Garden Planning and Design#

Package: @demeter/planner

10.1 Layout Engine#

• Canvas-based designer — Interactive garden layout canvas with element manipulation: add, remove, move, rotate, resize, copy.
• Grid snapping — Precise element placement with configurable grid alignment.
• Layer management — Multiple visual layers for beds, paths, structures, and water features.
• Undo/redo history — Full undo/redo capability for non-destructive editing.
• Area calculations — Automatic calculation of total garden area, individual bed area, and plantable space.
• Shape support — Multiple bed shapes, path types, structure types, and water feature elements.

10.2 Plant Placement#

• Square-foot gardening — Grid-based placement following the Square Foot Gardening methodology (Mel Bartholomew): each square foot accommodates a specific number of plants based on their mature size. For example, 16 carrots per square foot, but only 1 tomato plant per 4 square feet.
• Row planting — Traditional row planting layout with customizable row and plant spacing.
• Spacing validation — Automatic detection of plants placed too close together for healthy growth.
• Companion compatibility — Real-time companion planting compatibility checking as plants are placed.
• Mature size overlap — Detection of canopy overlap at maturity.
• Vertical space planning — Planning for vertical growing with trellises, cages, and support structures.

10.3 Sun and Shadow Analysis#

Understanding sun exposure is fundamental to garden design — placing a sun- loving tomato in a shaded spot will produce very little fruit.

• Solar position calculation — Accurate sun altitude and azimuth calculation for any location, date, and time.
• Sunrise/sunset times — Precise sunrise and sunset for any date.
• Daylength calculation — Day length computation across seasons for photoperiod-sensitive crops. Photoperiodism is the response of plants to the relative length of day and night — strawberries, onions, and cannabis all respond to day length to trigger flowering.
• Structure shadows — Shadow casting analysis from buildings, fences, and other structures throughout the day.
• Tree shadows — Tree shadow modeling accounting for canopy shape, height, and seasonal leaf cover.
• DLI calculation — Daily Light Integral (DLI) is the total amount of photosynthetically active radiation received per day (in mol/m²/day). Most vegetables need 20–30 DLI; lettuce can grow with 12–15. DLI is calculated from PPFD and photoperiod.
• Sun exposure zone classification — Classify garden areas as full sun (6+ hrs), partial sun (4–6 hrs), partial shade (2–4 hrs), or full shade.
• Sun heatmap — Visual heatmap of cumulative daily sun exposure across the entire garden layout.

10.4 Garden Templates#

• Template library — Pre-built templates for common garden types: vegetable, herb, flower, container, raised bed.
• Difficulty and zone filtering — Filter templates by experience level and hardiness zone compatibility.
• Custom templates — Create and save templates for reuse or sharing.

10.5 Export and Reporting#

From a garden plan, automatically generate:

• Plant shopping lists with quantities
• Seed order lists with quantities and supplier pricing
• Materials lists (soil, compost, lumber, hardware, drip tape)
• Planting calendars derived from specific plants in the plan
• Bed labels and row markers for physical identification
• Full JSON plan export for backup and cross-device transfer

11. Crop Rotation and Succession Planting#

11.1 Crop Rotation#

Crop rotation moves plant families to different beds each season to prevent the buildup of soil-borne diseases and pests specific to that family, and to balance soil nutrient depletion and replenishment.

• Plant family grouping — Classification by botanical family (nightshades/ Solanaceae, brassicas/Brassicaceae, legumes/Fabaceae, alliums/Alliaceae, etc.) with documented soil impacts per family.
• Four-year rotation plans — Automated generation of four-year plans cycling families through all beds.
• Rotation validation — Check for agronomic violations: the same family cannot follow itself; nitrogen fixers (legumes) should ideally precede heavy feeders.
• Next crop suggestions — Smart recommendations for which crop to plant next based on what was previously grown.
• Nitrogen balance tracking — Soil nitrogen contribution (legumes) and depletion tracking across rotation years.
• Cover crop planning — Cover crop recommendations for off-season soil improvement, including species selection and termination timing. Cover crops prevent erosion, fix nitrogen, and suppress weeds.
• Perennial accounting — Track permanent perennial placements (asparagus, perennial herbs) that do not rotate.

11.2 Succession Planting#

• Sowing interval calculation — Optimal sowing intervals based on days to maturity and desired harvest window length.
• Succession plan creation — Multi-sowing plans for continuous harvest of quick-maturing crops (lettuce, radishes, cilantro).
• Seed quantity calculation — Total seed needed across all succession sowings including germination rate adjustments.
• Harvest timelines — Visual harvest timeline showing expected production windows across all succession plantings.
• Actual vs. planned tracking — Compare planned succession dates against actual sowing and harvest dates to improve future planning.

12. Hydroponic Systems#

Package: @demeter/hydroponics

12.1 System Management#

Seven hydroponic system types are supported:

EC (electrical conductivity) and TDS (total dissolved solids) are measures of nutrient concentration in the solution — the higher the EC, the more dissolved minerals. Most vegetables grow well at 1.5–3.0 mS/cm EC.

• Setup cost estimation — Total component cost for building from a template.
• Power consumption — Daily electricity cost calculation.
• Crop recommendations — Best crops for each system type.

12.2 Nutrient Management#

• EC/TDS range management — Electrical conductivity targets per growth stage (seedling, vegetative, flowering, fruiting).
• pH adjustment calculations — Dosage recommendations for pH-up (potassium hydroxide) and pH-down (phosphoric acid) solutions.
• Nutrient lockout detection — Identify pH-induced nutrient lockout: when pH is outside the optimal range (5.5–6.5), specific nutrients become chemically unavailable even if present in the solution.
• Deficiency diagnosis — Symptom-based nutrient deficiency identification from visual plant symptoms (yellowing patterns, leaf distortion, necrosis).
• Brand profiles — Nutrient brand database (General Hydroponics, Advanced Nutrients, Megacrop) with mixing ratios.
• Mixing recipe calculation — Custom recipes from target EC and nutrient ratio specifications.

12.3 Reservoir Management#

• Water level monitoring — Threshold alerts for low, critical, and refill levels.
• Temperature control — Water temperature monitoring. Root zone temperature should ideally be 65–72°F; warmer water holds less dissolved oxygen and promotes pathogen growth.
• pH auto-dosing — Command generation for automated pH adjustment systems.
• Evaporation rate calculation — Days-until-refill estimation based on current level and consumption rate.
• Cleaning schedules — Automated cleaning schedules with method recommendations.
• Anomaly detection — Unusual reading detection for pH swings, EC spikes, and temperature excursions.

13. Aquaponics#

13.1 Fish Management#

Aquaponics combines aquaculture (fish farming) and hydroponics in a symbiotic system: fish waste provides nutrients for plants; plants filter the water for fish.

• Fish species database — Database of aquaponic fish species (tilapia, trout, catfish, goldfish, koi) with temperature preferences, growth rates, and difficulty ratings.
• Stocking density calculations — Maximum fish count based on tank volume and filtration capacity.
• Feeding calculations — Feeding amount and schedule calculations based on fish count, size, and water temperature.
• Species compatibility — Check temperature and behavior compatibility when keeping multiple species.
• Growth tracking — Weight measurements and feed conversion ratio (FCR) calculation — kg of feed per kg of fish gained.

13.2 System Balance#

• Nitrogen cycle monitoring — Track ammonia, nitrite, and nitrate levels. The nitrogen cycle is the biological process by which beneficial bacteria convert toxic fish ammonia (NH3) → nitrite (NO2) → nitrate (NO3), which plants then absorb. New systems require 4–6 weeks for the cycle to establish.
• Fish-to-plant ratio — Calculation of optimal fish biomass to grow bed area ratios for nutrient balance.
• Fish disease diagnosis — Symptom-based disease identification with treatment recommendations.

14. Indoor Growing and Controlled Environment#

14.1 Lighting#

• Grow light database — LED, HPS (High Pressure Sodium), and CMH (Ceramic Metal Halide) grow lights with PAR (Photosynthetically Active Radiation) output, spectrum, and efficiency ratings.
• DLI calculation — Daily Light Integral (DLI) calculated from PPFD (Photosynthetic Photon Flux Density, in µmol/m²/s) and photoperiod hours. DLI = PPFD × photoperiod hours × 3600 / 1,000,000.
• PPFD at distance — Light intensity calculation at various mounting heights accounting for beam spread.
• Photoperiod scheduling — Automated light schedule generation for vegetative (18h light) and flowering (12h light) photoperiods.
• Light cost comparison — Electricity cost comparison across grow light technologies for the same growing area.

14.2 Environment Control#

• VPD calculation — Vapor Pressure Deficit (VPD) measures the difference between the moisture the air could hold (saturation vapor pressure) and how much it actually holds. VPD drives transpiration — the process by which plants draw water and nutrients up through roots. Too low VPD (humid air): disease risk and poor nutrient uptake. Too high VPD (dry air): plant stress and wilting. Optimal indoor VPD is typically 0.8–1.5 kPa.
• VPD chart generation — Visual chart showing optimal VPD zones by growth phase (propagation, seedling, vegetative, flowering).
• CO2 supplementation planning — CO2 enrichment increases photosynthesis rates. Plants evolved in ~280 ppm CO2; supplementing to 1000–1500 ppm can increase yields by 20–30% under adequate light.
• Electricity cost estimation — Total electricity cost for lighting, ventilation, and climate control.

15. Microgreens Production#

Microgreens are vegetable seedlings harvested at the cotyledon or first true leaf stage (7–21 days after sowing), typically 1–3 inches tall. They contain higher concentrations of certain nutrients than mature vegetables and are harvested for culinary and nutritional use.

• Variety database — Microgreen varieties with germination time, grow time, difficulty rating, and flavor profile (mild, spicy, nutty, earthy).
• Tray lifecycle management — Complete management from seeding through blackout period (promotes germination), growing, and harvest.
• Seed density calculations — Optimal seed density per tray size for even coverage and maximum yield.
• Production scheduling — Multi-tray staggered production scheduling for continuous daily or weekly harvest.
• Profitability ranking — Variety ranking by profit margin accounting for seed cost, grow time, and market value — critical for commercial microgreen operations.
• Biological efficiency tracking — Yield per unit of seed and substrate cost.

16. Mushroom Cultivation#

16.1 Species Database#

Species catalog covering: oyster (Pleurotus ostreatus), shiitake (Lentinula edodes), lion's mane (Hericium erinaceus), reishi (Ganoderma lucidum), king oyster, turkey tail, and others.

• Culinary vs. medicinal filtering — Separate browsing by culinary use and documented medicinal properties.
• Difficulty ratings — Match species to grower experience level (oyster mushrooms are beginner-friendly; truffles are expert-only).
• Substrate matching — Species-to-substrate compatibility. Each species has preferred substrates: oysters grow well on straw, hardwood sawdust, and spent coffee grounds; shiitake prefers oak sawdust.

16.2 Cultivation Management#

• Substrate recipes — Preparation recipes with ingredient ratios, sterilization methods (autoclaving vs. pasteurization), and hydration targets (field capacity testing).
• Spawn calculations — Spawn quantity based on substrate weight and target inoculation rate (typically 10–25% spawn-to-substrate ratio by weight).
• Colonization tracking — Progress tracking with timeline estimation. Colonization is the period when mycelium (the fungal root network) is spreading through the substrate before fruiting can begin.
• Biological efficiency (BE) — Fresh mushroom yield as a percentage of dry substrate weight. 100% BE means 1 kg of dry substrate produced 1 kg of fresh mushrooms. Premium oyster crops can exceed 100% BE across multiple flushes.
• Flush management — Multi-flush harvest tracking. After each harvest (flush), the block rests and rehydrates before producing another flush.
• Contamination identification — Identify contamination types (green trichoderma mold, cobweb mold, wet spot bacterial infection) with severity assessment.
• Fruiting condition validation — Verify that temperature, humidity, CO2, and light conditions meet species requirements before initiating pinning.

17. Seed and Supply Inventory#

Package: @demeter/inventory

17.1 Seed Inventory#

• Seed lot tracking — Individual lot management with quantity, purchase date, source, and storage conditions.
• Viability tables — Species-specific data showing expected germination rates by seed age. Onion seeds are viable for only 1–2 years; tomato seeds can remain viable for 4–5 years under proper storage.
• Germination rate estimation — Estimated germination percentage based on seed age, species, and storage conditions.
• Expiration monitoring — Alerts for seed lots approaching or past their expected viability window.
• Shopping list generation — Automated shopping lists based on garden plan needs minus current inventory.

17.2 Supplier Management#

• Supplier database — Seed supplier directory with ratings, catalog listings, and order history.
• Germination tracking by supplier — Germination success rates tracked per supplier to identify reliable sources.
• Price comparison — Cross-supplier price comparison for the same varieties including shipping costs.

17.3 Seed Saving#

• Saving guides — Species-specific guides with difficulty ratings. Tomatoes are easy (self-pollinating, fermentation processing); corn is difficult (wind-pollinated, requires large population for genetic diversity).
• Isolation distance calculations — Minimum distances to prevent unwanted cross-pollination. Open-pollinated corn needs 300–1000 feet of isolation.
• Population requirements — Minimum plant population sizes needed to maintain genetic diversity.
• Lineage tracking — Seed lineage records tracking parent plants across generations (important for maintaining or improving variety characteristics).

17.4 Plant and Supply Inventory#

• Live plant tracking — Inventory with status: seedling, hardening off, transplanted, established.
• Hardening-off schedules — Hardening off is the gradual acclimation of indoor seedlings to outdoor conditions over 7–14 days. Without it, tender seedlings exposed suddenly to sun, wind, and temperature fluctuation suffer transplant shock. The system generates day-by-day increasing outdoor exposure schedules.
• Supply management — Consumable supply tracking (soil, fertilizer, mulch) with quantity monitoring and reorder alerts.
• Tool inventory — Durable tool management with maintenance scheduling, lending/return tracking.

18. Garden Journaling#

Package: @demeter/journal

18.1 Observations and Records#

• Daily observations — Structured entries with weather conditions, plant status, and activity notes.
• Photo management — Photo attachments with tagging, before/after comparisons, and gallery organization.
• Growth tracking — Plant measurement records: height, spread, flowering date, and fruiting records over time.
• Harvest logging — Harvest records with weight, quality rating, and per-plant yield tracking — essential for evaluating variety performance season-over-season.
• Pest and disease observation — Record first sightings and monitor progression of pest and disease issues.
• Weather correlation notes — Link observations to weather conditions for later pattern analysis.

18.2 Search and Insights#

• Full-text search — Search across all journal entries with date range and tag filtering.
• AI-powered insights — Pattern identification from journal data: identifying which varieties consistently outperform, predicting future issues based on historical patterns.
• Seasonal summaries — Automated summary generation from accumulated observations at the end of each season.

19. Post-Harvest Preservation#

Package: @demeter/preservation

All preservation methods follow USDA and NCHFP (National Center for Home Food Preservation) guidelines. These are the scientifically validated standards for safe home food preservation developed by the USDA and the University of Georgia, covering pH requirements, processing times, and safety verification.

19.1 Harvest Planning#

• Yield forecasting — Harvest yield prediction using crop yield databases and growing condition factors.
• Peak harvest prediction — Prediction of peak harvest windows for planning preservation sessions in advance.
• Container needs — Jar, bag, and tray quantity calculations for planned preservation volumes.
• Session scheduling — Preservation session planning with time estimates and priority ordering.

19.2 Canning#

• Water bath canning — For high-acid foods (pH < 4.6): fruits, jams, pickles, tomatoes with added acid. Heating to 212°F destroys most pathogens.
• Pressure canning — For low-acid foods (pH > 4.6): vegetables, meats, beans. Must reach 240°F to destroy Clostridium botulinum spores that cause botulism — a potentially fatal form of food poisoning. Water bath canning of low-acid foods is unsafe.
• Altitude adjustments — Automatic altitude-adjusted processing times. At higher altitudes, water boils at lower temperatures, requiring longer processing times.
• Botulism risk assessment — Risk assessment based on pH, acidity, processing method, and altitude — the most safety-critical feature.
• Batch management — Track batches from preparation through processing with seal checking records.
• USDA/NCHFP compliance — All recipes and processing times validated against official safety guidelines.

19.3 Freezing#

• Blanching guides — Produce-specific blanching instructions. Blanching (briefly boiling then ice-bathing) deactivates enzymes that cause flavor, color, and texture degradation in frozen vegetables.
• FIFO prioritization — First In, First Out inventory management prioritizes oldest items to prevent quality loss.
• Expiration alerting — Alerts for frozen items approaching quality expiration dates (most vegetables maintain best quality for 8–12 months at 0°F).

19.4 Dehydrating#

• Temperature guides — Dehydrating temperature and time guides per produce type (fruits: 135°F, herbs: 95°F, jerky: 160°F).
• Reconstitution ratios — Dried-to-fresh ratios for cooking with dehydrated ingredients.
• Shelf life estimation — Expected shelf life based on drying completeness and storage conditions (airtight, cool, dark).
• Fruit leather and jerky recipes — Specialized recipes for these popular dehydrated products.

19.5 Fermentation#

• Lacto-fermentation support — Lacto-fermentation uses naturally present Lactobacillus bacteria to convert sugars to lactic acid, creating a self-preserving acidic environment. Sauerkraut, kimchi, and dill pickles are lacto-fermented.
• Kombucha tracking — Fermentation batch management for kombucha (fermented tea) with SCOBY health tracking.
• Salt-for-brine calculations — Precise salt concentration calculations (typically 2–3% salinity by weight for vegetables). Too little salt allows harmful bacteria; too much inhibits the beneficial Lactobacillus.
• pH tracking — pH measurement logging with safety assessment against food safety thresholds.
• Safety assessment — Ferment safety evaluation based on pH readings, visual inspection, and process adherence.

19.6 Root Cellar and Produce Storage#

• Storage condition management — Temperature and humidity monitoring for root cellar, pantry, and cold storage locations.
• Condition compliance checking — Verify actual conditions against produce- specific requirements. Apples need 32–36°F and 90% humidity; winter squash needs 50–55°F and 50–70% humidity.
• Compatibility checking — Prevent ethylene-producing items (apples, pears, bananas) from accelerating ripening in neighboring produce.
• Rotation scheduling — Ensure older produce is used before newer stock.

20. Task and Schedule Management#

Package: @demeter/tasks

• Task scheduling — Garden tasks with due dates, recurrence patterns (daily, weekly, monthly, seasonally), and priority levels.
• Automated task generation — Automatic task creation from garden plans based on planting dates, care schedules, and harvest windows. Adding a tomato plant to a garden plan automatically generates: transplant date, first fertilization, first staking, weekly watering tasks, and expected harvest window.
• Smart prioritization — Dynamic task prioritization considering weather forecasts, plant conditions, and seasonal urgency (e.g., harvest before frost elevates priority).
• iCal calendar integration — Export garden tasks to standard iCal format for integration with Google Calendar, Apple Calendar, and Outlook.
• Task analytics — Completion rates, time spent, and seasonal workload patterns.

21. Community Gardening Platform#

Package: @demeter/community

21.1 Gardener Profiles#

• Rich profiles — Experience level, gardening interests, growing zone, garden statistics (plants grown, seasons active).
• Badge and achievement system — Bronze/silver/gold/platinum badges awarded automatically based on gardening milestones.
• Follow/block/mute — Social relationship management.
• Activity feeds — Personalized feeds showing followed gardeners' posts, harvests, and achievements.
• Location-based discovery — Find nearby gardeners using haversine distance calculation with configurable radius.

21.2 Seed and Plant Exchange#

• Exchange marketplace — Marketplace for seed swaps, plant divisions, and produce sharing.
• Distance-based search — Find exchanges within a reasonable geographic area.
• Reputation scoring — Ratings and successful transaction history.
• Wishlist matching — Automatic notifications when matching listings appear.

21.3 Groups and Community Gardens#

• Group management — Community garden groups with membership workflows, roles (admin, moderator, member), and privacy settings.
• Threaded discussions — Discussion posts with replies, likes, and pinning.
• Events with RSVP — Group event creation with RSVP tracking and attendee limits (workshops, planting days, harvest festivals).
• Shared resources — Community tool library with checkout/return tracking.
• Garden plot assignment — Community garden plot management with assignment, status, and waitlist.

21.4 Expert Network#

• Verified expert profiles — Credentials, specialties, and verification status for certified horticulturists, master gardeners, and domain specialists.
• Q&A platform — Question and answer system with voting and answer acceptance.
• Consultation booking — Expert consultation scheduling with time slot management.
• Article publishing — Expert article lifecycle: draft → review → publish → archive.

21.5 Content Sharing#

• Before/after posts — Photo comparison posts for garden transformations.
• Garden plan sharing — Share plans with the ability for others to fork and adapt them.
• Community challenges — Gardening challenges with entry submission, voting, and results.

22. Agricultural Analytics#

Package: @demeter/analytics

• Yield analytics — Season-by-season harvest yield comparison per crop, bed, and garden.
• Cost analysis — Garden cost tracking: seeds, amendments, water, and labor with ROI calculations (cost per kg of produce).
• Resource optimization — Water, fertilizer, and time efficiency analysis with specific recommendations.
• Environmental impact — Carbon offset calculation (home growing vs. commercial supply chain), water conservation, and biodiversity metrics (pollinator plants, perennial coverage).
• Time analytics — Task time tracking and labor efficiency by garden area and activity type.
• Success metrics — Overall garden success scoring from yield, plant health, task completion rates, and cost efficiency.

23. AI-Powered Agricultural Intelligence#

Package: @demeter/intelligence

• Plant identification — Image-based species identification from photographs.
• Disease detection — Visual disease diagnosis from plant symptom photographs.
• Pest identification — Image and symptom-based pest identification with confidence scoring.
• Growth prediction — ML-based harvest date prediction from sensor data and weather patterns.
• Personalized recommendations — Planting, care, and harvest recommendations based on garden history and local conditions.
• Sensor anomaly detection — Automatic detection of unusual sensor readings indicating equipment malfunction or extreme environmental conditions.
• Natural language interface — Conversational queries: "Why are my tomato leaves curling?" or "What should I plant in the empty corner bed next to the squash?"
• Model management — ML model versioning, deployment, and performance tracking across all intelligence features.

24. Data Foundation#

Package: @demeter/core

• 30 Zod schemas — Comprehensive runtime validation covering plants, gardens, beds, plantings, soil tests, weather, pests, sensors, and more.
• Type inference — TypeScript types inferred from Zod schemas for compile-time type safety without duplication.
• Drizzle ORM schema — Full relational database schema defined in Drizzle ORM covering all domain entities.
• Seed data — Initial reference data for bootstrapping: plant families, USDA zone definitions, common pest profiles.
• Plant type enumerations — Vegetable, fruit, herb, flower, tree, shrub, vine, grass, succulent, fern.
• Plant lifecycle enumerations — Annual (completes life cycle in one season), biennial (two seasons), perennial (returns each year).

Library Summary#

25. Applications#

The 14 libraries are consumed by three applications under apps/demeter/.

25.1 REST API (@demeter/api)#

A Fastify-based REST API that exposes garden management over HTTP. It depends on @demeter/core for shared schema and types.

• Versioned routes — all functional routes are mounted under /v1: gardens and beds, plants, plantings, tasks, harvests, sensors, weather, observations, AI, and community. Health probes (/health, /health/ready, /health/startup) are unversioned and unauthenticated.
• Authentication — email/password (bcrypt-hashed), refresh-token rotation with family-based theft detection, OAuth2 sign-in (Google, Apple, Facebook), passwordless magic links, and API keys for IoT devices. Sessions can be listed and revoked.
• Authorization — a five-role RBAC model (owner > admin > member > viewer, plus a non-hierarchical iot_device role) with twelve fine-grained permissions, backed by resource-ownership checks.
• Infrastructure — PostgreSQL via Drizzle ORM on a connection pool, Redis for caching and rate-limiting, Zod-validated configuration, Pino structured logging, Swagger/OpenAPI documentation, and CORS.

25.2 Web App (@demeter/web)#

A React single-page application built with Vite, React Router, TanStack Query, Zustand, Tailwind CSS, and Recharts.

• Coverage — around 62 page components spanning dashboard, gardens, plants, plantings, tasks, harvests, sensors, weather, journal, analytics, community, profile, and settings.
• Garden planner — both a 2D layout planner and a 3D garden planner page.
• Testing — unit tests with Vitest and end-to-end tests with Playwright.

25.3 Mobile App (@demeter/mobile)#

A React Native application on Expo SDK 52 with React Navigation, TanStack Query, and Zustand.

• Coverage — around 50 screens across auth, gardens, plants, journal, sensors, tasks, weather, community, AI, and settings.
• Offline-first — an offline subsystem provides an action queue, conflict resolution, a sync engine, plant and weather caches, and an offline photo manager.
• Platform integrations — a widgets layer adds Siri Shortcuts, Google Assistant, Watch support, quick actions, and notification actions.

26. Domain Boundaries#

Demeter is deliberately scoped to home gardening and small-scale cultivation. Four adjacent domains handle related concerns, and understanding where Demeter's responsibility ends prevents feature duplication.

Gaia — weather and climate forecast generation. Demeter consumes Gaia products rather than generating its own forecasts. Specifically, Demeter uses Gaia for localized garden weather, frost and heat alerts, growing-degree-day enrichment, precipitation and irrigation timing, chill-hour analysis, pest/disease risk context, and climate-aware plant recommendations. The boundary is clear: Demeter owns the garden decisions and user-facing automation rules; Gaia owns forecast generation and forecast skill verification.

Hestia — cooking, meal planning, and ingredient sourcing. The boundary between Demeter and Hestia runs through the post-harvest moment. Demeter handles growing the food and preserving it (canning, freezing, dehydrating, fermenting). Once preserved produce enters the pantry or kitchen, Hestia takes over with meal planning, recipe recommendations, and seasonal ingredient sourcing. Yield records and preservation inventories are the data that crosses this boundary.

Asase — commercial agricultural operations. Asase handles the same agricultural subject matter at commercial and industrial scale. Demeter does not model commodity pricing, supply chain logistics, farm management for operations with paid labor, or agribusiness compliance. If a feature only makes sense for a backyard gardener or a community plot — not a commercial farm — it belongs in Demeter.

Airmid — botanical and phytotherapy intelligence. Both Demeter and Airmid understand plant biology, but their purposes diverge. Demeter knows how to grow a plant: spacing, companions, pests, harvest window. Airmid knows a plant's therapeutic and pharmacological properties: active compounds, clinical applications, traditional medicinal use. A feature about cultivating a medicinal herb belongs in Demeter; a feature about its therapeutic dose or drug interactions belongs in Airmid.