OpenFarm

OpenFarm is a local-first progressive web app for small Vietnamese farms that combine gardens, ponds, and livestock. It supports farm design, daily operations, IoT monitoring, curated knowledge, and a read-only AI advisor that cites its sources.

Product principles

• One owner manages one farm and can invite a small team.
• Each farm is an isolated SaaS tenant.
• The PWA remains useful when connectivity is unreliable.
• Farm planning starts with a simple logical canvas and can add GIS geometry later.
• IoT integrations use adapters and canonical telemetry instead of vendor-specific domain logic.
• AI advises with evidence and cannot mutate farm data or control devices.

Architecture

Angular PWA ──REST/SSE──> Modular monolith ──> PostgreSQL/Object storage
                               │
Farm gateway ──MQTT────────────┤
                               └──> Workers: outbox, alerts, indexing

The approved system design is in docs/superpowers/specs/2026-07-26-openfarm-system-design.md.

Workspace

apps/
  web/       Angular 22 PWA
  api/       NestJS/Fastify modular monolith
  worker/    Background jobs
  gateway/   Farm-side IoT adapter runtime
packages/
  contracts/ Versioned public contracts
  domain/    Framework-free domain rules
  sync/      Offline synchronization protocol
  testing/   Shared fixtures and simulators

Prerequisites

• Node.js 22.22.3+, 24.15.0+, or 26+
• npm 11 or newer
• Docker with Compose for PostgreSQL integration tests

Setup

npm install

Installing dependencies configures the repository Git hooks through Husky.

Start the local platform database and apply forward migrations:

docker compose -f infra/compose.yaml up -d postgres
export OPENFARM_ADMIN_DATABASE_URL='postgresql://openfarm_admin@127.0.0.1:55432/openfarm'
npm run db:init
npm run db:migrate

Quality commands

npm run format        # Format supported source and documentation
npm run format:check  # Verify formatting without writing
npm run lint          # ESLint, Stylelint, and Markdownlint
npm test              # Repository and product tests
npm run test:api:integration
npm run test:api:operations:integration
npm run test:worker:integration
npm run test:iot:integration
npm run test:iot:recovery
npm run test:api:knowledge:integration
npm run test:knowledge:integration
npm run test:knowledge-ai:recovery
npm run test:e2e:sync # Production PWA offline/reconnect/multi-tab browser gate
npm run test:e2e:farm-twin # Production PWA Farm Twin + GIS browser gate
npm run test:e2e:operations # Production PWA Task/Journal offline browser gate
npm run test:e2e:production # Production PWA R2 Production Management browser gate
npm run test:e2e:tenant-export # Production PWA R2 Tenant Export browser gate
npm run test:e2e:saas # Production PWA R3 SaaS plan/quota browser gate
npm run test:e2e:iot # Production PWA IoT browser gate
npm run test:e2e:iot-http-json # Production PWA R2 HTTP JSON device adapter browser gate
npm run test:e2e:knowledge-ai # Production PWA Knowledge/AI browser gate
npm run test:e2e:r1-pilot # Production PWA R1 pilot lifecycle browser gate
npm run check         # Full local quality gate

Git hooks apply the same policy incrementally:

• pre-commit runs lint-staged on changed files.
• commit-msg enforces Conventional Commits.
• pre-push runs the complete npm run check gate.

Documentation

• System design
• OpenDesign primitives implementation plan
• Local platform runbook
• Local-first sync runbook
• Farm Twin R1 runbook
• Offline Operations R1 runbook
• Production Management R2 runbook
• Beta hardening runbook
• SaaS scale runbook
• Knowledge/AI R1 runbook
• Roadmap execution index

Status

The R0 foundation and R1 MVP pilot are runnable: Angular PWA, tenant membership/RBAC, invitation lifecycle, PostgreSQL RLS, idempotent mutations, transactional outbox, worker claim adapter, OpenTelemetry propagation, durable IndexedDB projections/outbox, push/pull sync, explicit conflict recovery and offline/reconnect/multi-tab browser acceptance, logical Farm Twin canvas, immutable design versions, typed review plans, optimistic/idempotent Farm Twin publish, Task/WorkLog/Journal offline operations, IoT simulator/telemetry/alert acknowledgement, Knowledge upload/indexing and advisory AI answers with exact citations. R1 pilot lifecycle evidence is guarded by npm run test:e2e:r1-pilot plus npm run test:e2e:knowledge-ai, npm run test:knowledge:integration, npm run test:knowledge-ai:recovery and npm run check. Local machines without the required PostgreSQL/S3/MQTT/Playwright service environment may fast-fail with environment_unavailable; CI wires the service-backed commands. R3 SaaS plan/quota/manual billing evidence is guarded by npm run test:e2e:saas and the SaaS scale runbook. R2 Production Management is Complete for ProductionCycle, immutable inventory/cost/harvest and derived economics: source, API integration, disposable-database browser PASS, security audit and runbook closeout are guarded by npm run test:e2e:production. R2 PostGIS UI và GeoJSON import/export geometry are Complete through Farm Twin API/PWA evidence and npm run test:e2e:farm-twin. R2 tenant export has service-backed browser and support read-only audit evidence via npm run test:e2e:tenant-export; backup/recovery closeout PASS is covered by npm run test:beta-hardening:recovery on Node 24.18.0 local service env. R2 IoT now includes the HTTP JSON real-device gateway adapter behind OPENFARM_GATEWAY_ADAPTER=http-json; browser acceptance for that beta path, R3 support, analytics and marketplace capabilities stay tracked roadmap work.