HORIZON (Cồn Hô)
Environmental monitoring platform for a farming community on Cồn Hô, an
island in Vĩnh Long, Vietnam. Originally built as "Eco-Sense Cồn Hô" — that
name persists in some technical identifiers (npm workspace scopes) and is
not renamed without a deliberate migration.
For the real, current, source-verified architecture — station topology,
what's live vs. not yet deployed, whether GCP is required — see
docs/ARCHITECTURE.md. This file is a short
front door only; it is not the source of truth for architecture claims.
Slides
The project presentation is a 20-slide Canva deck, HORIZON - FROGSLEAP VIETNAM,
shared alongside the website:
canva.link/frbq9egh4e8uuu7.
What this is
Three physical field devices (a water station, a soil station, and a
gateway) relay signed telemetry to a Supabase Edge Function, which
validates and stores it in Postgres. A Next.js PWA reads that data for a
public dashboard, per-station pages, a community field-report flow, and a
password-gated admin console. Full handbook: docs/README.md.
Repository structure
.
├── apps/web/ Next.js 15 PWA (public + admin)
├── services/edge-ingestion/ Telemetry validation logic + Deno edge function source
├── firmware/esp32-node/ ESP32 firmware (station1 / station2 / gateway)
├── infra/supabase/ SQL migrations, seed data, deploy/verify scripts
└── docs/ Product handbook — start at docs/README.md
Local development
npm install
npm run check # typecheck all workspaces
npm run test # edge-ingestion contract tests (mocked, no network)
npm run test:web # web app unit tests (mocked, no network)
npm run dashboard # start the Next.js app at http://localhost:4173
npm run simulator and npm run mock:ingest generate synthetic telemetry
for local UI development. Correction (Phase G): an earlier version of
this README claimed these write to a live Supabase project if pointed at
one — that was checked against the source and found to be wrong. Both
scripts hardcode MockDb (services/edge-ingestion/src/mockDb.ts) with
no network code path at all; simulator.ts only writes local files under
apps/web/mock/*.json, mock_ingest.ts only logs to the console. Neither
can write to a real Supabase project regardless of environment variables.
Test tiers — what's safe to run
| Command | Tier | Writes to live Supabase? |
|---|
npm run check, npm run lint | Static analysis | No |
npm run test, npm run test:web | Unit / mocked | No — no network calls |
npm run simulator, npm run mock:ingest | Synthetic telemetry generator | No — MockDb only, no network code path exists |
npm run test:rls | Mocked unless RUN_RLS_TESTS=1 | Yes if enabled — creates real throwaway users/assignments |
npm run test:integration, npm run test:all | Live integration | Yes if LIVE_SUPABASE_INTEGRATION=1 — POSTs real signed telemetry through edge-ingest |
test:rls and test:integration/test:all are the only commands that
require caution — both need deliberately-set env vars and should not be
run against this project's live Supabase instance without a specific
reason. .github/workflows/ci-live-smoke.yml runs both on a weekly cron
if its GitHub secrets are configured — see docs/ARCHITECTURE.md for the
current status of that workflow.
Environment variables
NEXT_PUBLIC_SUPABASE_URL=
NEXT_PUBLIC_SUPABASE_ANON_KEY=
SUPABASE_SERVICE_ROLE_KEY=
See apps/web/README.md for the full list including
admin-auth variables.
Current status
Backend and frontend are live against a real Supabase project (migrations
27 tracked migrations applied, including the additive 024/025 gateway and
timezone follow-ups). Three GitHub Actions workflows
exist under .github/workflows/ (validation on every PR/push, a weekly
live-integration smoke test, and a tag-triggered release/deploy pipeline)
— and the current token-authenticated gateway route retains real observation
envelopes and promotes their nested water/soil readings. Physical installation
and field calibration are not established by the repository alone.
See docs/ARCHITECTURE.md
for the exact current-vs-future boundary, and
docs/EDGE_INGEST_READINESS.md for what's
blocking a real deployment.
License
All rights reserved unless otherwise specified.
