Architecture

The repository is a Stacks application. It serves three surfaces from one codebase: the marketing site, the farmer console, and the public API. All three read the same data through one layer, which is the single most important property of the design.

The path a fact takes

app/Support/content/*.ts        authored content, the source of truth
        │
        │  buddy catalog:sync   truncates and rewrites
        ▼
database (features, use_cases, farms, fields, missions,
          detections, treatment_maps)
        │
        │  app/Support/catalog.ts   the one read layer
        ▼
   ┌────────────────┬────────────────────┐
   │ resources/views│ app/Actions/Catalog│
   │  (the site)    │   (the API)        │
   └────────────────┴────────────────────┘

Nothing renders a figure it typed itself. If /features and /api/features ever disagree, that is a bug rather than a stale copy.

What lives where

The domain model

Twelve models, of which ten describe the operation.

Farm ──┬── Field ──┬── Mission ──┬── Detection
       │           │             └── TreatmentMap
       │           │
       ├── Drone ──┘
       └── FarmCapability

Mission.purpose carries a feature slug. That is what connects the capability catalog on the marketing site to the flights that actually happened over a field, with no join table in between.

Denormalised keys are deliberate

Mission.farm_id and Detection.field_id are both derivable by joining. They are stored anyway so a holding's flights and a field's findings are each one query. The seeder fills a declared key that comes out empty from the parent it points at.

Multi-tenancy

Two separate mechanisms, because there are two separate surfaces.

The console never accepts a farm id from the request. Every dashboard read re-derives the holding from the signed-in user through farmFor(userId), and every dashboard write does the same and ignores any farm the request names. A request cannot name a holding, therefore it cannot name somebody else's.

The generated REST endpoints, which come from the models' useApi traits, know nothing about tenancy on their own. app/Middleware/FarmScope.ts narrows them: a write carrying farm_id must name a farm the caller owns, and a read without one is answered with ?farm_id= pinned to their own holding. An account with no holding gets a 403 rather than an empty list, because an empty list reads as "you have nothing" rather than "you have not started yet".

The demonstration farm is unowned, which is what keeps the worked example out of somebody's real numbers.

Scheduling

app/Scheduler.ts runs ScheduleCapabilityFlights daily at 05:30 Europe/Berlin. It converts each active FarmCapability into planned Mission rows for the fields whose cadence has come round.

Three things it deliberately does not do:

• It does not schedule requested capabilities. Those need equipment on site or a licence check first, so a planned flight would be a promise the schedule cannot keep. See Capabilities that need a visit.
• It does not double-book. A field with an existing scheduled flight for the same capability is skipped, so a retry does not fill the calendar.
• It does not decide the aircraft.

Daily rather than hourly because cadences are measured in days.

Failure posture

Every dashboard query is guarded individually with a safely() wrapper that falls back rather than throwing. A dashboard that 500s because one panel's table has not been migrated is worse than a dashboard with one empty panel. The same reasoning applies in catalog.ts: an unseeded instance serves an empty catalog rather than an error page.