v4 Architecture System Map

Garden OS
System Map

A zero-backend horticultural reasoning engine built entirely in the browser.

Garden OS is an open-source raised bed planning system that runs as a collection of standalone single-file HTML tools with no server, no build step, and no cloud dependency. What began as a layout planner has evolved into a full horticultural reasoning engine — capable of evaluating crop placement, analyzing companion planting compatibility, modeling structural support requirements, and generating diagnostic explanations directly in the browser.
↗ Live Demo GitHub Repository Garden OS Home
01

Executive Summary

Garden OS is architected around four non-negotiable constraints: no backend, no build toolchain, no external data dependencies, and no required network connection after initial load.

Zero Backend
All computation runs in the browser. There is no server, no API endpoint, and no database. Every evaluation, score, and diagnostic is produced locally using JavaScript logic embedded in each tool file.
Single-File Architecture
Every tool in the ecosystem is a self-contained .html file. Inline CSS, inline JavaScript, and embedded data. Download it, open it, use it — no installation or toolchain required.
Horticultural Reasoning Engine
The planner has evolved past a drag-and-drop layout tool into a reasoning system that models crop compatibility, seasonal windows, structural constraints, and limiting factors at the bed level.
Portable Workspace
The entire workspace state serializes to a human-readable .gos.json file. Workspaces are fully portable across machines, browsers, and time — no lock-in to any platform or service.
02

System Layers

Garden OS is organized into four vertical layers. Each layer has a clearly bounded responsibility and communicates with adjacent layers through defined interfaces rather than shared mutable state.

UI User Interface Layer
Planner
Inspect Panel
Scoring Visualizer
Build Guide
Ops Guide
Landing Page
Logic Application Logic Layer
Crop Scoring Engine
Adjacency Analyzer
Season Evaluator
Structural Support Model
Limiting Factor Detector
Data Data Model Layer
Workspace Model
Bed Layout Records
Crop Database
Cage Configuration
Site Settings
JSON Schema
Persist Persistence Layer
localStorage
.gos.json Export
.gos.json Import
03

Data Flow

Every user edit initiates a deterministic evaluation pipeline. No side effects, no asynchronous calls to external services, no hidden state. The full evaluation cycle runs synchronously in the browser.

User Edits Layout
The user places, moves, or removes a crop in the planner grid. The interaction is handled by the UI layer and dispatches a workspace mutation event.
Workspace Updates
The Workspace Model receives the mutation. Bed layout records are updated. The updated workspace state is passed downstream to the scoring pipeline.
Scoring Engine Evaluates Crop Placement
The Crop Scoring Engine runs against the full bed layout, consulting the Crop Database for compatibility data, spacing requirements, and yield profiles.
Adjacency Analyzer Checks Neighbors
Each cell in the layout is evaluated against its immediate neighbors. Companion planting relationships, root competition, and canopy interference are resolved.
Limiting Factor Identified
The Limiting Factor Detector determines the single highest-priority constraint blocking optimal placement — sun, spacing, antagonism, structural support, or season.
Inspect Panel Explains Result
The Inspect Panel surfaces the scored result and the identified limiting factor as a human-readable diagnostic. No codes, no jargon — plain operational language.
Workspace Persists Locally
The updated workspace state is serialized and written to localStorage automatically. No save button, no sync latency. State is durable across browser sessions.
Optional Export Generates .gos.json
On user request, the workspace model serializes to a fully portable .gos.json file. The file is human-readable, versionable, and loadable in any Garden OS tool instance.
04

Engineering Principles

These principles are not aspirational — they are constraints enforced at the architecture level. A feature that violates any of them does not ship.

Zero Backend
No server receives user data, no API key is required, and no account is necessary. All computation happens on the user's machine. The system works fully offline after the initial file download.
Offline First
Garden OS is designed to function without a network connection. No CDN assets, no remote fonts on a cold load, no external service calls. The tool is the file. The file is enough.
Deterministic Scoring
Given identical input, the scoring engine always produces identical output. There is no randomness, no server-side ML inference, and no user-specific weighting that could produce divergent results.
Portable Workspace Files
The .gos.json format is the canonical workspace representation. It is version-controlled friendly, human-readable, and designed to remain loadable by future versions of any Garden OS tool.
Single HTML Tool Architecture
Every tool ships as one self-contained .html file. No build step, no dependency resolution, no bundler configuration. This is a deliberate constraint, not a shortcut.
Human Readable Diagnostics
The system communicates in plain language. Scores are explained, limiting factors are named, and recommendations reference observable conditions in the garden — not numeric codes or internal identifiers.
05

Tool Ecosystem

Garden OS ships as a coordinated set of single-file tools, each with a bounded scope. Tools share the .gos.json workspace format as their common interface.

Planner Core
The primary planning interface. Drag-and-drop crop placement, live scoring feedback, adjacency analysis, and bed configuration. The central tool in the ecosystem and the main entry point for users.
planner.html — single file
Build Guide Guide
Generates a context-aware bed construction guide based on the user's workspace configuration — dimensions, materials, structural requirements, and cage setup instructions.
build-guide.html — single file
Ops Guide Guide
Produces a season-specific operational guide for the loaded workspace: watering schedules, fertilization timing, crop succession notes, and maintenance tasks derived from the active bed layout.
ops-guide.html — single file
Scoring Visualizer Visual
An interactive heat map of the scoring engine's output. Renders placement scores, adjacency weights, and limiting factor overlays across the entire bed grid for visual diagnostics.
scoring-visualizer.html — single file
Scoring System Map Meta
Technical documentation of the scoring engine itself: rule weights, factor definitions, adjacency matrices, and algorithm behavior. Designed for contributors and advanced users extending the system.
scoring-map.html — single file
Landing Page Meta
Project overview, tool index, and quick-start guide. Links to all tools in the ecosystem, the GitHub repository, and the documentation set. Deployable as a static file with no server.
index.html — single file