Architecture - Clavion

What you will learn

How Clavion is organized as a monorepo of specialized packages
The role of each package in the transaction pipeline
How components communicate across trust domain boundaries

System overview

Clavion is a monorepo of 14 TypeScript packages, each belonging to exactly one trust domain. The packages are connected by TypeScript project references and npm workspaces.

┌────────────────────────────────────────────────┐
│           Domain A (Untrusted)                 │
│  adapter-openclaw  adapter-mcp  plugin-eliza   │
│  adapter-telegram                              │
│       │              │              │          │
│       └──────────────┼──────────────┘          │
│                      │ HTTP (localhost:3100)    │
├──────────────────────┼─────────────────────────┤
│           Domain B (Trusted)                   │
│                      ▼                         │
│              ┌─── core ───┐                    │
│              │  API Server │                   │
│              │  TX Builders│                   │
│              └─────┬───────┘                   │
│         ┌──────────┼──────────┐                │
│      policy    preflight   signer              │
│      audit     registry                        │
├────────────────────────────────────────────────┤
│           Domain C (Limited Trust)             │
│              sandbox                           │
│       (Docker containers, no keys)             │
└────────────────────────────────────────────────┘

Package responsibilities

Domain A — Untrusted (Agent Adapters)

Package	Purpose
`@clavion/adapter-openclaw`	OpenClaw skill wrappers with ISCLClient
`@clavion/adapter-mcp`	MCP server exposing 6 tools for Claude Desktop / Cursor
`@clavion/plugin-eliza`	ElizaOS plugin with 5 actions + wallet provider
`@clavion/adapter-telegram`	grammY-based Telegram bot with inline approval

All Domain A packages share a common pattern: construct a TxIntent, send it to ISCL Core via ISCLClient (HTTP), and return the result.

Domain B — Trusted (ISCL Core)

Package	Purpose
`@clavion/core`	Fastify API server, TX builders, approval service, RPC routing
`@clavion/signer`	Encrypted keystore (scrypt + AES-256-GCM), wallet service
`@clavion/audit`	Append-only SQLite audit trail, rate limiting
`@clavion/policy`	Policy engine with configurable rules
`@clavion/preflight`	Transaction simulation via `eth_call`, 7-factor risk scoring
`@clavion/registry`	Skill manifest validation, ECDSA signature verification
`@clavion/types`	Shared TypeScript interfaces and JSON schemas

Domain C — Limited Trust (Sandbox)

Package	Purpose
`@clavion/sandbox`	Docker container runner with aggressive isolation

Communication model

All cross-domain communication flows through the ISCL Core HTTP API:

Domain A  ──HTTP──▶  Domain B (ISCL Core API, port 3100)
Domain C  ──HTTP──▶  Domain B (ISCL Core API, port 3100)

Domain A and Domain C never communicate directly
No shared memory, no direct function calls, no file-based channels
The API is bound to 127.0.0.1 — only local processes can connect

Technology stack

Component	Technology	Rationale
Language	TypeScript (ESM, Node 20+)	Type safety, ecosystem
API	Fastify + JSON Schema	Performance, strict validation
EVM	viem	Modern, typed, tree-shakeable
Validation	AJV (strict mode)	Fast, standard-compliant
Database	SQLite via better-sqlite3	Embedded, zero-config, WAL mode
Encryption	scrypt + AES-256-GCM	Industry standard key encryption
Hashing	JCS + keccak256	Deterministic canonicalization
Sandbox	Docker	Process isolation, resource limits
Testing	vitest	Fast, ESM-native

Next steps

Trust Domains — Deep dive into the isolation model
Transaction Lifecycle — The execution pipeline in detail
ADR-001: Trust Domain Isolation — Formal design rationale

​What you will learn

​System overview

​Package responsibilities

​Domain A — Untrusted (Agent Adapters)

​Domain B — Trusted (ISCL Core)

​Domain C — Limited Trust (Sandbox)

​Communication model

​Technology stack

​Next steps