Architecture

Architecture

High-Level Design

NemoClawd uses a bridge-first architecture: the Node.js layer orchestrates all operations and calls into the Python layer when NeMo workflow execution is required. Results always flow back to Node as structured JSON.

┌─────────────────────────────────────────────────────┐
│                   ClawdBot Runtime                  │
│              (Node.js / TypeScript)                 │
│                                                     │
│   Canvas UI ──► Orchestrator ──► NemoBridge (TS)   │
└──────────────────────┬──────────────────────────────┘
                       │ JSON over stdio / HTTP
┌──────────────────────▼──────────────────────────────┐
│              NemoClawd Python Bridge                │
│                (nemoclawd-bridge)                   │
│                                                     │
│         subprocess ──► nat CLI                      │
└──────────────────────┬──────────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────────┐
│          NVIDIA NeMo Agent Toolkit                  │
│              (nat workflow engine)                  │
│                                                     │
│   Workflow YAML ──► Agent ──► Tools ──► Results    │
└─────────────────────────────────────────────────────┘

---

Components

1. ClawdBot Runtime (apps/clawdbot-main/)

The Node.js/TypeScript production runtime. Handles:

• Canvas UI rendering and branding
• User interaction and session management
• Outbound transcript mirroring
• Orchestration of all AI operations

2. NemoBridge (src/nemo-bridge.ts)

The TypeScript bridge module. Responsible for:

• Spawning the Python bridge subprocess
• Serialising requests to JSON
• Deserialising structured responses
• Error handling and timeout management

3. NemoClawd Python Bridge (python_src/nemoclawd_bridge/)

A lightweight Python package that:

• Receives JSON requests from NemoBridge
• Invokes nat CLI commands
• Returns structured JSON results to Node
• Handles NeMo workflow lifecycle

4. NeMo Agent Toolkit (apps/NeMo-Agent-Toolkit-develop/)

NVIDIA's full NeMo Agent Toolkit. Provides:

• nat CLI for workflow execution
• Agent definitions and tool integrations
• Evaluation and profiling infrastructure
• HITL (Human-in-the-Loop) support

5. System-of-Record (system-of-record.json)

The identity anchor. Verified at launch by scripts/verify-system-of-record.mjs. Contains:

• Runtime identity configuration
• Build metadata
• Capability declarations

---

Data Flow

Standard Request

User Input
  └─► ClawdBot Orchestrator
        └─► NemoBridge.execute(workflow, params)
              └─► Python Bridge (subprocess)
                    └─► nat run <workflow>.yml --params <json>
                          └─► NeMo Agent executes tools
                                └─► Structured JSON result
              ◄── JSON response
        ◄── Parsed result object
  ◄── Rendered response to user

Build Flow

pnpm run build:all
  ├─► tsc (TypeScript compilation)
  ├─► build-node.mjs (Node bundle)
  ├─► bootstrap-python.mjs (venv setup)
  ├─► build-python.mjs (wheel build)
  └─► collect-artifacts.mjs (output staging)

---

File Structure

NemoClawd/
├── src/
│   ├── index.ts              # Entry point
│   └── nemo-bridge.ts        # NemoBridge implementation
├── python_src/
│   └── nemoclawd_bridge/
│       ├── __init__.py
│       └── __main__.py       # Python bridge entry point
├── scripts/
│   ├── bootstrap-python.mjs  # Python venv setup
│   ├── build-node.mjs        # Node bundle build
│   ├── build-python.mjs      # Python wheel build
│   ├── collect-artifacts.mjs # Artifact staging
│   ├── run-clawdbot-with-nemo.mjs  # Launch script
│   ├── smoke-test.mjs        # Integration smoke test
│   └── verify-system-of-record.mjs # SoR validation
├── apps/
│   ├── clawdbot-main/        # ClawdBot Node.js runtime
│   └── NeMo-Agent-Toolkit-develop/  # NVIDIA NeMo Toolkit
├── artifacts/                # Build outputs and logs
├── workflows/                # NeMo workflow definitions
├── system-of-record.json     # Identity anchor
├── package.json              # Node workspace config
├── pyproject.toml            # Python package config
├── tsconfig.json             # TypeScript config
├── Dockerfile                # Container build
└── docker-compose.yml        # Compose services