🌱 Amfor-Cast Gardener — Developer Documentation

Internal docs. Architecture, API reference, deployment, and data model.

Architecture

┌─────────────────────────────────────────────────────────┐
│  Pi Cron (hourly)                                       │
│  └─ save-forecast.py → AMFOR blend → MySQL             │
└──────────────────────────┬──────────────────────────────┘
                           │ (amforcas_forecasts DB)
┌──────────────────────────┼──────────────────────────────┐
│  gardener.amfor-cast.com │                              │
│  ├─ index.html (SPA)     │  /api/plants.php             │
│  │   ├─ Plant Now        │    ├─ ?action=now            │
│  │   ├─ My Garden        │    ├─ ?action=catalog        │
│  │   ├─ Catalog          │    ├─ ?action=plant&slug=X   │
│  │   ├─ Companions       │    ├─ ?action=companions     │
│  │   └─ Calendar         │    ├─ ?action=weather        │
│  │                       │    ├─ ?action=full_calendar   │
│  ├─ user-guide.html      │    └─ ?action=categories     │
│  └─ dev-docs.html (🔒)   │                              │
└──────────────────────────┴──────────────────────────────┘
        │                                    │
        ▼                                    ▼
┌───────────────────────┐  ┌──────────────────────────────┐
│  amforcas_gardener DB │  │  amforcas_forecasts DB       │
│  ├─ plants (154 rows) │  │  ├─ forecasts + hours        │
│  ├─ planting_calendar │  │  ├─ users, sessions          │
│  ├─ companions        │  │  └─ (shared with main app)   │
│  ├─ plant_care        │  └──────────────────────────────┘
│  └─ user_garden       │
└───────────────────────┘

Two databases: amforcas_gardener for plant data (catalog, calendar, companions) and amforcas_forecasts for weather data (shared with the main amfor-cast.com app). The API uses get_gardener_db() for plant queries and get_db() for weather.

Frontend Routing

Hash-based SPA routing. The URL reflects the current view:

URL Hash	View	Function
`#now`	Plant Now	`loadWhatNow()`
`#mygarden`	My Garden	`renderMyGarden()`
`#catalog`	Catalog	`loadCatalog()`
`#companions`	Companions	`renderCompanions()`
`#calendar`	Calendar	`renderCalendar()`
`#plant/slug`	Plant detail	`loadPlantDetail(slug)`

Tab switches push history via history.pushState(). The popstate listener handles back/forward. Search, city change, and language toggle do NOT push history entries.

API Reference

Endpoint	Method	Description
`?action=now&month=N`	GET	Plants active in month N (default: current). Grouped by activity.
`?action=catalog&category=X&difficulty=X`	GET	Full plant list with optional filters. Includes current month activities.
`?action=plant&slug=X`	GET	Single plant detail with calendar, companions, care instructions.
`?action=companions&ids=1,2,3`	GET	Companion matrix for selected plant IDs + suggestions.
`?action=weather&city=budapest`	GET	7-day forecast from AMFOR model (fallback: ICON → Best match). Uses `amforcas_forecasts` DB.
`?action=full_calendar`	GET	All calendar entries for all plants (for year overview).
`?action=categories`	GET	Plant count by category (dynamic).

Database Schema

plants

Master plant catalog (~154 rows). Key fields:

Column	Type	Purpose
`slug`	VARCHAR(50) UNIQUE	URL-safe identifier
`name_en / name_hu`	VARCHAR(100)	Bilingual names
`category`	ENUM	vegetable, fruit, herb, flower, green_manure, tree, shrub, perennial, evergreen, groundcover, climber
`subcategory`	VARCHAR(50)	Finer grouping (nightshade, legume, cucurbit, root, leafy, etc.)
`frost_sensitive`	TINYINT	1 = dies at frost
`min_soil_temp_c`	FLOAT	Min soil temp for germination
`seed_depth_cm`	FLOAT	How deep to plant
`spacing_cm`	INT	Between plants
`days_to_harvest_min/max`	INT	Growing duration range
`description_en/hu, tips_en/hu`	TEXT	Bilingual content

planting_calendar

When to do what. References plants.id.

Column	Purpose
`activity`	sow_indoor, sow_outdoor, transplant, harvest, prune
`month_start / month_end`	Active window (1-12)
`zone`	USDA zone (default: 7a = Hungary)
`notes_en / notes_hu`	Bilingual activity notes

companions

Bidirectional relationships between plants.

Column	Purpose
`plant_id_a / plant_id_b`	The two plants
`relationship`	good, bad, neutral
`reason_en / reason_hu`	Why

Category System

11 categories in the ENUM. Frontend shows 9 in the filter (excluding flower and green_manure which have ≤3 plants each but are still searchable).

Category	Icon	Count	Examples
vegetable	🥬	38	tomato, pepper, carrot, cabbage
perennial	🌾	27	yarrow, sedum, fescue, ornamental grasses
tree	🌳	16	oak, maple, ash, goldenrain
shrub	🪻	16	smoke tree, hawthorn, privet, roses
fruit	🍓	14	raspberry, grape, strawberry, kiwi
groundcover	🪴	13	thyme, clover, rupturewort, barrenwort
evergreen	🌲	10	juniper, pine, yew, cedar, yucca
herb	🌿	9	basil, rosemary, oregano, mint
climber	🧗	5	clematis, honeysuckle, trumpet vine
flower	🌻	3	marigold, nasturtium, sunflower
green_manure	🌱	3	white clover, mustard, strawberry clover

Themes

Three themes stored in localStorage('gardener_theme'):

Theme	Icon	Style
garden	🌿	Light green, clean (default). No `data-theme` attribute.
emerald	✨	Dark green glassmorphism. `data-theme="emerald"`
prism	💎	Purple/pink frosted glass. `data-theme="prism"`

The theme button cycles through all three. Each theme overrides CSS custom properties and adds specific card/button styles via [data-theme="X"] selectors.

Weather Integration

The ?action=weather endpoint (uses amforcas_forecasts DB):

Queries forecasts for the latest snapshot where model='AMFOR' and city=?
Falls back to ICON → Best match if AMFOR not available
Joins forecast_hours for the next 7 days of hourly data
Computes daily aggregates: temp min/max, precip sum, wind max
Estimates soil temp: 3-day avg air temp − 2°C (heuristic)

⚠️ Soil temperature estimate is a rough heuristic. Consider integrating Open-Meteo's soil temperature API for more accuracy in the future.

Deployment

# Deploy all gardener files:
./gardener/deploy.sh

# Manual single-file deploy:
scp gardener/index.html amforcas@amfor-cast:/home/amforcas/gardener.amfor-cast.com/

# SQL imports (run on server):
mysql -u amforcas_admin -pDeltaechomary_45 amforcas_gardener \
  --default-character-set=utf8mb4 < file.sql

Server paths

Local	Server
`gardener/`	`/home/amforcas/gardener.amfor-cast.com/`
`api/php/auth.php`	`/home/amforcas/public_html/api/php/auth.php` + `/api/auth.php`
`api/php/config.php`	`/home/amforcas/public_html/api/php/config.php` + `/api/config.php`

⚠️ There are TWO config.php files on the server (/api/config.php and /api/php/config.php). CORS origins must be added to BOTH. Same for auth.php.

SQL migration files

File	Purpose
`schema.sql`	Full schema (clean install)
`seed-data.sql`	Original 60 plants + calendar + companions
`seed-drought-tolerant.sql`	100 drought-tolerant Hungarian plants
`seed-drought-calendar.sql`	Calendar entries for drought plants
`seed-missing-calendar.sql`	Calendar entries for original plants that were missing them
`migrate-categories.sql`	Expand ENUM + reclassify drought plants to proper categories
`migrate-gardener-db.sh`	Move tables from amforcas_forecasts → amforcas_gardener

i18n Strategy

Plant data: stored in DB with _en / _hu columns. API returns both; frontend picks based on getLang().
UI strings: in the t() function in index.html. ~70 strings, static.
Category labels: in CATEGORY_LABELS object (bilingual).
Language state: localStorage('weather_lang'). Shared with main amfor-cast.com site.

Auth / Cross-domain

Cookie: amfor_session, domain=.amfor-cast.com, SameSite=None, Secure, HttpOnly
CORS: gardener.amfor-cast.com must be in ALLOWED_ORIGINS in both config files
Credentials: fetch(..., {credentials: 'include'}) for all cross-origin auth calls
Admin access: dev-docs restricted to username demogun

Data Storage

My Garden selection: localStorage (my_garden = JSON array of plant IDs). IDs coerced to Number for comparison.
City preference: localStorage (gardener_city = slug). Auto-detected from user profile if logged in.
Theme: localStorage (gardener_theme = garden|emerald|prism).
Language: localStorage (weather_lang = en|hu).

Future Work

Server-side My Garden (save to user_garden table when logged in)
Push notifications (frost alerts, harvest reminders)
Real soil temperature from Open-Meteo API
Plant-specific watering schedule based on 7-day forecast
Photo journal per plant
Disease/pest risk model (humidity + temp patterns)
Multi-zone support (different calendars for different regions)
PWA support (offline access, add to home screen)

🔒 Access Denied