Asoba Asoba Open Source

Architecture

Nehanda CLI is a layered, single-process engine with six distinct architectural layers. Every component runs in-process within Node.js (v22+) — eliminating external daemon processes, relay proxies, or container runtimes.

Nehanda CLI Architecture Diagram

Layer Overview

NEHANDA CLI — SYSTEM ARCHITECTURE 6-Layer In-Process Engine · Energy Systems Telemetry Normalization & Governed 11-Phase SDLC REPL / INK TUI Command Parser · BlockConfirmMenu · OS-Primitives Sandbox · Display Renderer /model wizard · /key · /config · /mcp · Live reasoning token spinner · Bounded cli-table3 output · Pipe mode bin/nehanda-ui.mjs lib/sandbox.mjs USER TURNS · INTERACTIVE MENUS ENGINE CORE Turn Loop (runUserTurn) · 11-Phase SDLC State Machine · Jev-Mem · Tool Orchestration idle→explore→diagnose→issue→tests→plan→implement→verify→safety→confirm→done · Laya System-1 · [TOOL_CALL] lib/orchestrate.mjs lib/workflow.mjs PHASE-FILTERED TOOL CALLS TOOL LAYER Built-in Tools (21) · 3 Safety Checkers · Branch Coverage Collector · MCP Client Read/Write/Edit/Bash/Glob/Grep · JsSafety/ShellSafety/PySafety · branch-coverage-collector · mcp__<server>__<tool> lib/tools.mjs lib/safety-gate.mjs RAW OEM TELEMETRY · MODBUS MAPS ODSE MIDDLEWARE OEM Brand Fingerprinting · ODSE Normalization · SCADA Table Transformation Huawei · Enphase · SolarEdge · Sungrow · Eskom · 20+ OEMs · name → fingerprint · --format table|ndjson energy-middleware.mjs odse-transform.py NORMALIZED PROMPTS · STREAMING PROVIDER LAYER Unified /model Wizard · Keyed Discovery · Isolated Credentials · Ollama Probes OpenRouter · Anthropic Claude · Ollama (native tool probe, think:false) · LM Studio · Zhipu · Nehanda 27B configureProvider.mjs openaiCompat.mjs PROVENANCE LOGS · MEMORY EDGES · WAL PERSISTENCE SQLite Database (Schema v4) — ~/.config/nehanda/ona-session.db WAL mode · FTS5 · test_executions (RED/GREEN provenance) · safety_evidence · red_evidence · pinned_context lib/store.mjs better-sqlite3 In-process execution · No background server daemons · No Docker containers required · Complete local provenance

Layer 1: REPL / Ink TUI

The user interface layer is built with Ink (React in the terminal).


Layer 2: Engine Core

The central orchestration engine runs entirely inside the host Node.js process:


Layer 3: Tool Layer


Layer 4: ODSE Middleware

Intercepts MCP results from energy assets and standardizes them to the ODS-E specification:


Layer 5: Provider Layer

Unified interface across frontier cloud providers and local open-source inference:


Layer 6: Persistence Layer (Schema v4)

Single-file, zero-daemon SQLite storage at ~/.config/nehanda/ona-session.db:


Cross-Cutting Concerns

Concern Description Reference
OS-Primitives Sandbox Disposable project snapshot (256 MiB / 10k entries); Seatbelt on macOS; Bubblewrap on Linux; network egress allowlist proxy Permissions & Sandbox
Epistemic Filter Redacts implementation blocks from assistant messages during test generation and verification SDLC Workflow
Database Migrations Automatic zero-downtime migration through schema versions v1 $\rightarrow$ v2 $\rightarrow$ v3 $\rightarrow$ v4 Database
Hook Plane Event-driven triggers (PreToolUse, PostToolUse, UserPromptSubmit, PhaseTransition) Hooks