How Apivera moves a hive record from the yard to a grower report
A walkthrough of the runtime topology, domain model, business flows, rule engine and data pipeline behind the platform.
Runtime topology
Three layers with one direction of dependency. Clients never reach the database directly; every write passes the permission and rule layer.
Client layer
- Next.js 14 App Router, React Server and Client Components
- Mobile-first inspection flows, tablet and desktop shells
- Mapbox GL for placement and route rendering
- Optimistic local state with route-level loading
Application layer
- Typed Node.js service boundary with REST resources
- Role and permission middleware per organization
- Rule engine for contract, treatment and movement guards
- Export workers for CSV and PDF generation
Data layer
- PostgreSQL with Prisma schema as the source of truth
- Row-scoped tenancy on organization identifiers
- Append-only audit trail for every state change
- Point-in-time recovery with a seven-day window
Edge delivery
Static shell and route prefetching
Mapbox tiles
Vector styles with cached sprites
Job queue
Exports, rollups and notifications
Audit sink
Append-only compliance log
Entity relationships
Every row is scoped to an organization. Colony history is immutable: inspections and treatments append rather than overwrite.
Organization
Apiary
Hive
Contract
Three flows carry the season
Select a flow to trace each step from the field action through to the record that a grower or auditor eventually reads.
Field inspection flow
Left to right in five stages. Each stage writes an audit entry.
Crew opens assigned yard
Task list scoped to the beekeeper's apiaries.
Inspection captured
Strength, queen status, brood frames, mite wash.
Hive record updated
Latest metrics written onto the colony row.
Rules evaluated
Mite threshold and queen loss raise follow-up tasks.
Rollups refreshed
Yard and contract averages recalculated.
Declarative guards on every write
Rules evaluate after validation and before commit. Warnings annotate the record; critical rules reject the transaction and return a remediation hint.
mite_pressure_guard
warningWheninspection.varroaPer100 ≥ 3
ThenCreate urgent treatment task, flag colony as monitored
queen_loss_escalation
warningWheninspection.queenStatus in (MISSING, PRESENT_NOT_LAYING)
ThenRaise requeen task with 7-day due date
contract_frame_minimum
criticalWhenavg(hive.broodFrames) < contract.minFramesAvg
ThenBlock deployment, propose substitute colonies
withdrawal_period_lock
criticalWhentreatment.withdrawAt > contract.startDate
ThenExclude colony from placement pool
capacity_ceiling
infoWhenapiary.hiveCount > apiary.capacity
ThenWarn on placement and suggest overflow yard
plan_limit_enforcement
infoWhenorganization.hiveCount > plan.hiveLimit
ThenPrompt upgrade before new colonies are created
Evaluation order
From field capture to grower export
01 · Capture
Inspection, treatment and movement events from the field
02 · Validate
Schema and permission checks at the service boundary
03 · Persist
Transactional write to PostgreSQL plus audit entry
04 · Derive
Colony, yard and contract rollups recomputed
05 · Serve
Dashboards, maps and reports read the derived views
06 · Export
CSV and PDF packs rendered by background workers
Permission matrix
Module access per role, enforced in the service layer and the navigation shell.
Non-functional targets
Budgets the build is held to.
- API p95< 250 ms
- Inspection save< 400 ms
- Map first paint< 1.2 s
- Export render< 8 s
- Uptime target99.9%
- Audit retention24 months