Skip to main content

Handbook

This document represents the master engineering reconstruction of the Helix Transfer Protocol (HxTP) platform, derived exclusively from a forensic analysis of its production source code.

1. Executive System Reconstruction​

Platform Overview & System Purpose​

The HxTP Cloud Platform is a hybrid deterministic/cognitive IoT control plane. Its primary business purpose is to provide a highly secure, multi-tenant messaging and command dispatch backbone for connected physical devices, while seamlessly integrating autonomous AI intelligence.

Architectural Philosophy​

The system operates on the principle of "AI Proposes, Kernel Disposes". It physically separates non-deterministic AI cognitive cycles (the Python Sidecar) from a rigidly deterministic safety, validation, and physical dispatch layer (the Node.js/TypeScript Kernel).

Operational & Runtime Model​

  • Execution: Event-driven, asynchronous processing model.
  • Trust Model: Strict Public-Key Identity. Every device holds a unique Ed25519 private key. The Cloud holds a Root Private Key. MQTT is treated as an untrusted transport secured by short-lived session tokens.
  • Scaling Philosophy: Horizontally scalable compute nodes (TS API and Python Sidecars) utilizing a centralized distributed state layer (Redis) and durable authoritative storage (Firestore).

2. Full System Architecture Diagram​

3. Complete Module Dependency Graph​

4. Runtime Execution Flow Documentation​

Application Boot Sequence​

Cognitive Request Lifecycle​

5. Database & State Architecture​

Entity Relationship Model​

Persistence Lifecycle​

  • Redis (Ephemeral): Holds request_id idempotency hashes (TTL based), device nonces, hx47 heartbeats, and circuit breaker health states.
  • Firestore (Durable): Holds authoritative configuration, user schemas, pending/dispatched offline commands, and tamper-evident audit logs.

6. API & Protocol Specification​

The HxTP/3.1 Protocol​

The system uses a rigidly enforced messaging protocol designed for edge devices. Required Fields (Canonical Pipe Framing):

  1. version (Must be exactly HxTP/3.1)
  2. device_id
  3. tenant_id
  4. client_id (MQTT Session Token)
  5. message_id
  6. request_id (Correlation ID)
  7. sequence_number (Monotonically increasing)
  8. timestamp (Unix Epoch)
  9. nonce (Stored in Redis to prevent replay attacks)
  10. message_type
  11. payload_hash (SHA-256 of parameters)

Trust Chain:

  • Device Key: Signs outbound telemetry, state, and HELLO handshake.
  • Cloud Root Key: Signs inbound commands and HELLO_ACK responses.
  • MQTT Token: Transport layer only; expires every 24 hours.

7. AI / Agent / Cognitive System Reconstruction​

The Cognitive Runtime Architecture​

The AI subsystem (hx47-core) operates as an independent, stateful process that interacts with the Node.js kernel entirely via gRPC.

Execution Guarantees​

  • Non-Deterministic Computation: The AI generates plans using a tool-calling loop (ReAct).
  • Infinite Loop Protection: Loop Guard monitors execution graphs, automatically compressing context or forcibly terminating cycles if the agent loops without state progress.
  • Authority Constraints: The AI has no capacity to directly interact with the physical world. It emits "Intents" back to the TS Kernel, which executes them physically only if the strict deterministic rule-engine (SafetyGateway) permits it.

8. Infrastructure & Deployment Blueprint​

Hosting Strategy: Containerized micro-platform.

  • API Nodes: Stateless Fastify workers (deployable via K8s or Docker Swarm). CPU-intensive RSA tasks are farmed out to a local Node.js WorkerPool.
  • Sidecar Nodes: Memory-intensive Python LLM context managers. Separated from the API to prevent blocking the TS event loop.
  • Network Boundaries: Reverse proxied by Nginx. Devices connect to Nginx over MQTTS (TCP/8883), which terminates TLS and forwards to Mosquitto. Mosquitto bridges pub/sub locally to the TS API.

9. Security & Trust Boundary Documentation​

Key Security Tenets Derived from Code:

  1. Device Isolation: Private keys never leave their respective boundaries (Device or Cloud HSM).
  2. Path Traversal Protection: Firmware uploads enforce strict regex validation (GetFileId).
  3. Fail-Closed Default: If Redis goes down, DependencyCircuitBreaker throws CRITICAL_DEPENDENCY_UNAVAILABLE, dropping requests rather than skipping idempotency checks.
  4. Mandatory Handshake: Devices cannot send commands until the HELLO handshake (v3.1) is accepted and state transitions to ACTIVE.

10. Conclusion & Operational Thesis​

The HxTP platform is a mature, production-grade command dispatch system that solves the fundamental challenge of integrating autonomous LLM cognition with high-stakes physical actuation.

By pushing the LLM into an unprivileged sidecar and forcing all outputs through a rigorously deterministic safety gateway, HxTP achieves the flexibility of cognitive reasoning without sacrificing the execution guarantees required for IoT operations. While minor scaling and entropy-related technical debts exist (which can be rectified with trivial patches to hash lengths and DB queries), the underlying distributed systems architecture is remarkably sound, reliable, and highly extensible.