HORTILINK ENGINEERING DOCUMENTATION FRAMEWORK

README — Master Entry Point Tanggal: 2026-02-24

HORTILINK ENGINEERING DOCUMENTATION FRAMEWORK
1. EXECUTIVE SUMMARY
- HortiLink Engineering Documentation Framework (HTL-00 s/d HTL-09)
2. Pendahuluan
3. ARSITEKTUR KERANGKA BESAR
4. STRUKTUR DOKUMENTASI & EXECUTION MAP
5. Tata Kelola Dokumen
6. Format Revisi
7. Kepemilikan Dokumen
8. Pengendalian Perubahan (Change Control)
9. PRODUCTION READINESS PIPELINE
10. MANFAAT UNTUK DOKUMEN DEVELOPMENT
11. POSISI STRATEGIS PROYEK

1. EXECUTIVE SUMMARY

HortiLink Engineering Documentation Framework (HTL-00 s/d HTL-09)

HortiLink dirancang sebagai platform kontrol pertanian terdistribusi berbasis site otonom, dengan arsitektur local-first dan server Raspberry Pi wajib per-site. Sistem terdiri dari Node (ESP sensor/actuator), relay-aware topology intra-site, Gateway ESP sebagai bridge, serta Server lokal sebagai broker, database, dan supervisory layer.

Dokumentasi HTL-00 sampai HTL-09 membentuk satu kerangka engineering terstruktur yang memastikan:

Pengembangan paralel antar tim
Kontrak komunikasi formal
Kontrol lokal tetap berjalan saat server/gateway gagal
Proteksi elektrikal dan mekanikal sesuai kondisi lapangan
Model keamanan per-site yang terkontrol
Validasi sistem sebelum produksi

Framework ini bukan sekadar dokumentasi teknis, tetapi struktur tata kelola engineering yang meminimalkan risiko kegagalan saat scale.

2. Pendahuluan

Direktori ini berisi dokumentasi teknis resmi untuk platform kontrol pertanian terdistribusi HortiLink.

Seluruh dokumen dengan awalan HTL-XX merupakan dokumen engineering formal dan wajib mengikuti proses revisi terkontrol sesuai tata kelola yang ditetapkan.

Dokumentasi ini berfungsi sebagai:

Sumber kebenaran arsitektur sistem
Kontrak komunikasi lintas tim engineering
Referensi resmi untuk QA dan tim lapangan
Gerbang validasi sebelum produksi (production gate)
Kerangka tata kelola engineering (engineering governance framework)

3. ARSITEKTUR KERANGKA BESAR

Secara sistemik, HortiLink per-site bekerja sebagai berikut:

Node (sensor + actuator + control lokal) → Relay-aware intra-site network → Gateway ESP → MQTT broker (Raspberry Pi) → DB + Dashboard + OTA + RBAC

Kontrol kritikal berada di Node. Gateway dan Server adalah supervisory. Internet tidak dibutuhkan untuk operasi dasar.

4. STRUKTUR DOKUMENTASI & EXECUTION MAP

4.1 HTL-Series (Formal Specification)

ID	Document Name
HTL-00	System Architecture Master Document
HTL-01	Interface Specification
HTL-02	Node Technical Specification
HTL-03	Gateway Technical Specification
HTL-04	Server (Raspberry Pi) Specification
HTL-05	HMI Specification
HTL-06	Electrical & Panel Design Specification
HTL-07	Security Architecture
HTL-08	Failure Mode & Recovery Matrix
HTL-09	Test Plan & Validation Matrix

HTL adalah spesifikasi.

4.2 Ringkasan Per Dokumen (HTL-00 s/d HTL-09)

HTL-00 – System Architecture Master Document

Peran: Dokumen arsitektur tertinggi.

Mengunci:

Boundary sistem per-site
Control hierarchy (Level 0–3)
Topologi komunikasi
Relay-aware model
Degradation mode
Capacity baseline (10–15 node/site)
Ketiadaan cloud pada fase awal

Tanpa HTL-00, semua dokumen lain akan ambigu.

HTL-01 – Interface Specification

Peran: Kontrak komunikasi lintas tim.

Mengunci:

MQTT topic structure
Payload schema
Command state machine
Idempotency
Retry/backoff
TTL rule
OTA metadata format
ESP-NOW frame structure

Ini memungkinkan Node, Gateway, dan Server dikembangkan paralel.

HTL-02 – Node Technical Specification

Peran: Spesifikasi firmware node.

Mengunci:

Sensor handling
Local control engine
Interlock safety
Relay-aware routing
Telemetry generation
Command validation
Watchdog
Brownout handling
OTA client

Node harus tetap aman walaupun gateway/server mati.

HTL-03 – Gateway Technical Specification

Peran: Spesifikasi bridge intra-site.

Mengunci:

ESP-NOW coordinator
Routing validation
Deduplication
Store-and-forward
Time authority
Rate limiting
MQTT bridging

Gateway tidak boleh menjadi control authority.

HTL-04 – Server Raspberry Pi Specification

Peran: Supervisory layer lokal.

Mengunci:

MQTT broker configuration
DB ingestion
Command management
Config versioning
OTA repository
RBAC
Backup
Monitoring

Server bukan kontrol kritikal, tetapi pusat observability dan orchestration lokal.

HTL-05 – HMI Specification

Peran: Interaksi manusia.

Mengunci:

Mode direct-to-node
Mode via server
Role-based access
Manual override policy
Alarm model
Audit trail

HMI tidak boleh melanggar interlock dan safety.

HTL-06 – Electrical & Panel Design Specification

Peran: Landasan keandalan fisik.

Mengunci:

Power topology
HV/LV separation
Inrush handling
Surge protection
Grounding
Brownout mitigation
Wiring standard

Tanpa HTL-06, sistem akan gagal secara fisik walau software benar.

HTL-07 – Security Architecture

Peran: Keamanan per-site.

Mengunci:

Identity model
MQTT ACL
ESP-NOW encryption
OTA integrity
RBAC
Key management
Audit logging

Fokus pada LAN security baseline.

HTL-08 – Failure Mode & Recovery Matrix

Peran: Manajemen risiko teknis.

Mengunci:

Failure domain
Detection method
Containment boundary
Recovery mechanism
Escalation owner
Degradation mode

Menjadi referensi QA dan troubleshooting lapangan.

HTL-09 – Test Plan & Validation Matrix

Peran: Verifikasi kesiapan produksi.

Mengunci:

Unit test
Integration test
Electrical validation
Failure injection
Stress test
Soak test
OTA validation
Security validation
Commissioning checklist

Tanpa HTL-09, tidak ada “Production Gate”.

4.3 DEV-HTL — Development Execution Framework

HTL adalah spesifikasi. DEV-HTL adalah eksekusi.

DEV-HTL-01 – Node Direct

Full firmware ESP32
Sensor & actuator driver
Interlock enforcement
HTTP direct commissioning
Watchdog & brownout
Definition of Done terikat HTL-09

DEV-HTL-02 – Node ↔ Gateway

Transport selection (LoRa / ESP-NOW)
Frame structure
Routing table
Dedup window
Retry/backoff deterministic
Hop limit enforcement

DEV-HTL-03 – Gateway ↔ Server

MQTT bridge
Store-and-forward buffer
SQLite WAL ingestion
Broker reconnect lifecycle
Health publish

DEV-HTL-04 – Server ↔ Cloud

HTTPS TLS sync
Spool queue SQLite
Batch upload idempotent
Exponential backoff
WAN degradation safe mode

DEV-HTL bukan narasi. Ia berisi hardware selection, OOP layering, coding, lifecycle, dan failure handling.

5. Tata Kelola Dokumen

HTL-00 harus diselesaikan dan disetujui sebelum HTL-01 dibekukan (freeze).
HTL-01 mendefinisikan kontrak komunikasi antara tim Node, Gateway, dan Server.
Tidak ada implementasi yang boleh menyimpang dari HTL-01 tanpa pembaruan revisi resmi.
Seluruh dokumen wajib memiliki bagian riwayat revisi (revision history).

6. Format Revisi

Format penomoran versi:

vMAJOR.MINOR.PATCH

Contoh:

v1.0.0 – Baseline awal
v1.1.0 – Penambahan bagian buffering pada gateway
v1.1.1 – Perbaikan kesalahan penulisan pada skema payload

Keterangan:

MAJOR: Perubahan arsitektur atau kontrak signifikan dan tidak kompatibel ke belakang.
MINOR: Penambahan fitur tetap kompatibel.
PATCH: Klarifikasi tanpa perubahan perilaku sistem.

7. Kepemilikan Dokumen

Setiap dokumen wajib mendefinisikan:

Pemilik dokumen (Owner)
Peninjau (Reviewer)
Otoritas persetujuan (Approval Authority)

Tanpa struktur kepemilikan yang jelas, tata kelola dokumen dianggap tidak sah.

8. Pengendalian Perubahan (Change Control)

Setiap perubahan pada HTL-00 atau HTL-01 wajib melalui rapat tinjauan arsitektur (architecture review meeting).

Perubahan terhadap boundary sistem atau kontrak komunikasi tidak boleh dilakukan secara sepihak oleh tim manapun.

9. PRODUCTION READINESS PIPELINE

Unit test
Integration test
Failure injection
WAN unplug test
Broker restart test
Brownout simulation
Soak test
HTL-09 validation

Tanpa lulus HTL-09 → tidak production ready.

10. MANFAAT UNTUK DOKUMEN DEVELOPMENT

Executive summary ini dapat digunakan untuk membuat dokumen:

Product Development Plan
Engineering Roadmap
Sprint Breakdown
Resource Allocation
Risk Register
Production Readiness Criteria

Karena:

Boundary sudah jelas
Tanggung jawab sudah terpisah
Interface sudah dikontrakkan
Failure sudah dipetakan
Test gate sudah didefinisikan

11. POSISI STRATEGIS PROYEK

Dengan HTL + DEV-HTL:

HortiLink bukan sekadar proyek IoT berbasis ESP.

Ia menjadi:

Distributed Autonomous Agricultural Control System

dengan:

Local reliability
Structured governance
Deterministic degradation
Secure transport
Production readiness
Multi-site scalability

Catatan Penyusunan Artikel ini disusun sebagai materi edukasi dan referensi umum berdasarkan berbagai sumber pustaka, praktik lapangan, serta bantuan alat penulisan. Pembaca disarankan untuk melakukan verifikasi lanjutan dan penyesuaian sesuai dengan kondisi serta kebutuhan masing-masing sistem.