Database Schema¶

Kamerplanter uses ArangoDB as its primary database — a multi-model system combining document and graph database capabilities. All entities are organized as document collections; relationships are modeled as edge collections in the named graph kamerplanter_graph.

Overview¶

Document Collections¶

Master Data (REQ-001)¶

Species — field propagation_configs¶

The propagation_configs object-array field is the canonical model for a species' propagation. Each PropagationConfig entry describes one propagation method together with its own timing, wood stage, difficulty and notes — replacing the former flat propagation_methods/propagation_months/propagation_notes fields. Subfields:

• method (required) — one PropagationMethod enum value: seed · cutting · leaf_cutting · division · rhizome_division · bulb · bulbil · tuber · offset · runner · grafting · layering · air_layering · water_propagation · tissue_culture · spore · self_seeding.
• months (list[int], range 1–12) — months in which this method is most suitable, deduplicated and sorted ascending on the server side, independent of the other configs. The species-level sowing windows for generative propagation remain in the separate direct_sow_months, indoor_start_months and transplant_months fields.
• wood_stage (WoodStage \| null) — softwood / semi_hardwood / hardwood / herbaceous; only meaningful for cutting-type methods.
• difficulty (PropagationDifficulty \| null) — easy / moderate / difficult.
• notes (string \| null, max. 1,000 characters) — free-text expert knowledge for this method: typical failure points, species-specific substrate or temperature requirements, acclimatisation steps.

The array is optional in SpeciesCreate (default: empty list) and always present in SpeciesResponse (empty list when not populated). It is maintained for most species in the seed data.

Note (deprecated flat fields): The flat fields propagation_methods/propagation_months/propagation_notes are deprecated in favour of propagation_configs. Legacy flat values are still accepted and adapted on import — one config per method, all sharing the flat propagation_months, with propagation_notes attached to the first method only. New data uses propagation_configs.

Species — field toxicity / allergen_info¶

The toxicity object field captures a species' toxicity separately for cats, dogs and children (is_toxic_cats/is_toxic_dogs/is_toxic_children), the affected plant parts (toxic_parts), the responsible compounds (toxic_compounds) and the severity (severity: none/mild/moderate/severe). allergen_info adds contact- and pollen-allergen flags. The flat passthrough field toxicity_severity (low/moderate/high) is preserved from historical data and is not mapped onto toxicity.severity. All fields are optional (null when not maintained).

Species — field seed_profile¶

The seed_profile object field bundles genuine seed/germination metadata for seed-propagated species: germination temperature range (germination_temp_min_c/_max_c), sowing depth (sowing_depth_cm), days to germination (days_to_germination), seed viability in years (seed_viability_years), light/dark germination (light_germination: light/dark/indifferent), pretreatment (pretreatment: cold_stratification/warm_stratification/scarification/presoak), thousand-seed weight (thousand_seed_weight_g) and sowing density (sowing_density_per_m2). All fields are optional; purely vegetatively propagated species leave the object empty (null).

Locations and Infrastructure (REQ-002, REQ-019)¶

Plant Instances and Runs (REQ-013)¶

Planting run states:

planned → active → harvesting → completed
                             → cancelled

Irrigation and Fertilization (REQ-004, REQ-014)¶

Pest Management — IPM (REQ-010)¶

Harvest (REQ-007)¶

Tasks and Workflows (REQ-006)¶

Authentication and Users (REQ-023)¶

Tenants and Memberships (REQ-024)¶

Roles per tenant: admin, grower, viewer

Care Reminders (REQ-022)¶

Onboarding (REQ-020)¶

Propagation (REQ-017)¶

Miscellaneous¶

Edge Collections (Graph Relationships)¶

Master Data Graph¶

Location Graph¶

Plant Instance Graph¶

Planting Run Graph¶

Tank and Fertilization Graph¶

IPM Graph¶

Harvest Graph¶

Task Graph¶

Tenant Graph¶

Indexes¶

Kamerplanter automatically creates the following indexes on startup:

Tenant Data Isolation¶

All tenant-bound resources carry a tenant_key field. On each request the FastAPI dependency get_current_tenant resolves the tenant from the /t/{tenant_slug}/ URL segment and rejects the call if the requesting user holds no active membership there. Writing endpoints additionally require a permission: require_permission(resource, action) for creating/updating/deleting tenant-bound resources, require_tenant_role for a plain minimum role, and require_admin_scope for administrative surfaces (member management, integrations). At the data level the isolation additionally comes from every write path stamping tenant_key out of the resolved tenant context, and every query filtering on that field.

Global resources (no tenant binding): species, cultivars, botanical_families, pests, diseases, treatments, starter_kits

Tenant-bound resources: sites, locations, plant_instances, planting_runs, tanks, fertilizers, nutrient_plans, tasks

Technical Notes for Developers¶

• Collections and the named graph are automatically created and migrated by ensure_collections() at backend startup.
• Add new collections or edge definitions to collections.py — they are created on the next startup.
• AQL queries use FOR ... IN GRAPH kamerplanter_graph exclusively for graph traversals.
• _key and _id are ArangoDB-internal identifiers. Application keys (e.g. instance_id) are separate fields with hash indexes.

See Also¶

• API Reference
• Environment Variables
• Backend Architecture