# hugger-mugger/soth architecture

> Architecture diagram of the GitHub repository hugger-mugger/soth, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hugger-mugger/soth
- Repository: https://github.com/hugger-mugger/soth

## Overview

1. **Repository shape.** This is a Rust workspace centered on a local edge-governance runtime, with supporting CLI tooling, shared domain crates, optional cloud sync, language bindings, and two extension ecosystems. The main architectural boundary is between the **on-device control plane** and the **optional SOTH Cloud backend**.

2. **Primary runtime: `soth-cli` + `soth-proxy`.** `soth-cli` is the operator-facing entrypoint. It installs the local CA, starts/stops the proxy daemon, manages config, enrollment, events streaming, and self-update. `soth-proxy` is the long-running network interceptor and enforcement engine.

3. **Traffic interception boundary.** The proxy sits between AI agents and external services. It selectively terminates TLS for configured AI-provider domains and transparently tunnels everything else. It handles HTTP(S), streaming responses, and other agent-facing transports, while keeping unrelated traffic out of the trust boundary.

4. **Decision pipeline inside the proxy.** Requests flow through staged gating logic before forwarding: TLS/origin checks, app-origin validation, whitelist/blacklist checks, app-type checks, and host-origin checks. That gating layer decides whether traffic is allowed, blocked, or specially handled, and it is the main policy enforcement seam.

5. **Shared domain model.** `soth-core` holds the common primitives used across the system: identities, requests, sessions, observations, policy, providers, telemetry, crypto, and normalized event types. `soth-api-types` defines the serialized API/wire shapes and conversions, so the proxy, sync layer, bindings, and cloud-facing code all speak the same contract.

6. **Classification and detection pipeline.** `soth-classify` provides a multi-stage classification pipeline used to infer use cases, volatility, anomalies, policy signals, and telemetry enrichment, with optional ONNX-backed models. `soth-detect` contains deterministic detection helpers for sensitive/code/stream parsing and replay logic. Together these form the “understand what the traffic means” layer that feeds policy and observability.

7. **Policy is a separate engine.** `soth-policy` isolates policy evaluation, including synchronous policy logic and corpus-driven tests. This keeps enforcement decisions distinct from transport handling and makes policy a pluggable, testable subsystem rather than ad hoc code inside the proxy.

8. **Local storage and observability.** `soth-telemetry` is the local SQLite-backed store for captured events. The proxy also has its own session store and observability modules for redaction, tracing, and local state. In standalone mode, this local store is the system of record; nothing needs to leave the machine.

9. **Optional cloud sync path.** `soth-sync` is the bridge to SOTH Cloud. It handles enrollment, config and registry pulls, body uploads, heartbeat, retry/outbox semantics, and telemetry replay. This is an opt-in pipeline that moves locally captured data to the managed dashboard/fleet backend; the proxy remains fully functional without it.

10. **Bundle and update infrastructure.** `soth-bundle` and the bundle-related modules in core/proxy manage signed, versioned bundle artifacts used for detection/gating/classification data. The CLI also has update/download/swap code and a sidecar updater for replacing binaries safely across OSes. This is how rules/model/data updates flow into the runtime without coupling them to the application code.

11. **Extension layer for agent ecosystems.** `extensions/code` parses and adapts events from specific AI coding tools such as Claude Code, Codex, Cursor, Gemini CLI, OpenCode, Pi Agent, and Windsurf, turning tool-specific events into a common hook/event model. `extensions/historian` backfills and normalizes historical records from JSON, JSONL, or SQLite sources. These are integration boundaries rather than core enforcement logic.

12. **Language bindings and SDKs.** The repo exposes native bindings for Node (`soth-node`), Python (`soth-py`), Go (`soth-go`), and an edge/browser wrapper (`soth-edge`). The bindings layer is where ecosystem-specific instrumentation and integrations live, while the core Rust crates remain the authoritative implementation. Cross-language conformance tests protect that boundary.

13. **Validation and release scaffolding.** The workspace includes contract, corpus, and FFI conformance tests across proxy, detect, telemetry, sync, bindings, and extensions. CI workflows and the `ops`/`scripts` directories support signed releases, installation, and operational rollout, but the runtime architecture itself is organized around the local proxy + store + optional sync model.

Main entry points: [`crates/soth-core`](https://github.com/hugger-mugger/soth/tree/main/crates/soth-core) (soth-core), [`crates/soth-proxy`](https://github.com/hugger-mugger/soth/tree/main/crates/soth-proxy) (soth-proxy), [`crates/soth-sync`](https://github.com/hugger-mugger/soth/tree/main/crates/soth-sync) (soth-sync), [`crates/soth-bundle`](https://github.com/hugger-mugger/soth/tree/main/crates/soth-bundle) (soth-bundle)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Local runtime"]
  node_soth_cli["soth-cli<br/>operator CLI"]
  node_soth_proxy["soth-proxy<br/>interceptor daemon"]
  node_proxy_gating["gating pipeline<br/>policy stages"]
  node_proxy_sessions[("sessions<br/>local state")]
  node_proxy_observability["observability<br/>redaction/tracing"]
  node_proxy_runtime["runtime core<br/>network handler<br/>[runtime.rs]"]
end

subgraph group_shared["Shared crates"]
  node_soth_core["soth-core<br/>domain core"]
  node_soth_api_types["api-types<br/>wire contract"]
  node_soth_policy["soth-policy<br/>policy engine"]
  node_soth_classify["soth-classify<br/>classification pipeline"]
  node_soth_detect["soth-detect<br/>detection engine"]
  node_soth_bundle["soth-bundle<br/>bundle loader"]
  node_soth_telemetry[("soth-telemetry<br/>sqlite store")]
end

subgraph group_cloud["Cloud sync"]
  node_soth_sync["soth-sync<br/>cloud bridge"]
end

subgraph group_bindings["Bindings"]
  node_soth_node["soth-node<br/>node binding"]
  node_soth_py["soth-py<br/>python binding"]
  node_soth_go["soth-go<br/>go sdk"]
  node_soth_edge["soth-edge<br/>edge wrapper"]
end

subgraph group_extensions["Extensions"]
  node_ext_code["extensions/code<br/>agent adapters"]
  node_ext_historian["extensions/historian<br/>historical import"]
end

node_soth_cli -->|"manages"| node_soth_proxy
node_soth_cli -->|"installs rules"| node_soth_bundle
node_soth_cli -->|"enrolls"| node_soth_sync
node_soth_proxy -->|"enforces"| node_proxy_gating
node_soth_proxy -->|"tracks"| node_proxy_sessions
node_soth_proxy -->|"emits"| node_proxy_observability
node_soth_proxy -->|"processes"| node_proxy_runtime
node_proxy_gating -->|"evaluates"| node_soth_policy
node_proxy_gating -->|"loads rules"| node_soth_bundle
node_proxy_runtime -->|"uses model"| node_soth_core
node_soth_policy -->|"shares domain"| node_soth_core
node_soth_classify -->|"consumes events"| node_soth_core
node_soth_classify -->|"feeds signals"| node_soth_detect
node_soth_detect -->|"reads bundles"| node_soth_bundle
node_soth_telemetry -->|"stores events"| node_soth_core
node_soth_sync -->|"speaks contract"| node_soth_api_types
node_soth_sync -->|"replays"| node_soth_telemetry
node_soth_sync -->|"pulls config"| node_soth_bundle
node_soth_node -->|"binds core"| node_soth_core
node_soth_py -->|"binds core"| node_soth_core
node_soth_go -->|"binds core"| node_soth_core
node_soth_edge -->|"wraps contract"| node_soth_api_types
node_ext_code -->|"normalizes"| node_soth_core
node_ext_historian -->|"imports"| node_soth_telemetry

click node_soth_cli "https://github.com/hugger-mugger/soth/tree/main/crates/soth-cli"
click node_soth_proxy "https://github.com/hugger-mugger/soth/tree/main/crates/soth-proxy"
click node_proxy_gating "https://github.com/hugger-mugger/soth/tree/main/crates/soth-proxy/src/gating"
click node_proxy_sessions "https://github.com/hugger-mugger/soth/tree/main/crates/soth-proxy/src/session"
click node_proxy_observability "https://github.com/hugger-mugger/soth/tree/main/crates/soth-proxy/src/observability"
click node_proxy_runtime "https://github.com/hugger-mugger/soth/blob/main/crates/soth-proxy/src/runtime.rs"
click node_soth_core "https://github.com/hugger-mugger/soth/tree/main/crates/soth-core"
click node_soth_api_types "https://github.com/hugger-mugger/soth/tree/main/crates/soth-api-types"
click node_soth_policy "https://github.com/hugger-mugger/soth/tree/main/crates/soth-policy"
click node_soth_classify "https://github.com/hugger-mugger/soth/tree/main/crates/soth-classify"
click node_soth_detect "https://github.com/hugger-mugger/soth/tree/main/crates/soth-detect"
click node_soth_bundle "https://github.com/hugger-mugger/soth/tree/main/crates/soth-bundle"
click node_soth_telemetry "https://github.com/hugger-mugger/soth/tree/main/crates/soth-telemetry"
click node_soth_sync "https://github.com/hugger-mugger/soth/tree/main/crates/soth-sync"
click node_soth_node "https://github.com/hugger-mugger/soth/tree/main/bindings/soth-node"
click node_soth_py "https://github.com/hugger-mugger/soth/tree/main/bindings/soth-py"
click node_soth_go "https://github.com/hugger-mugger/soth/tree/main/sdks/soth-go"
click node_soth_edge "https://github.com/hugger-mugger/soth/tree/main/bindings/soth-edge"
click node_ext_code "https://github.com/hugger-mugger/soth/tree/main/extensions/code"
click node_ext_historian "https://github.com/hugger-mugger/soth/tree/main/extensions/historian"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_soth_cli,node_soth_proxy,node_proxy_gating,node_proxy_sessions,node_proxy_observability,node_proxy_runtime toneBlue
class node_soth_core,node_soth_api_types,node_soth_policy,node_soth_classify,node_soth_detect,node_soth_bundle,node_soth_telemetry toneAmber
class node_soth_sync toneMint
class node_soth_node,node_soth_py,node_soth_go,node_soth_edge toneRose
class node_ext_code,node_ext_historian toneIndigo
```

## Components

### Local runtime

On-device control plane and enforcement path.

- [soth-cli](https://github.com/hugger-mugger/soth/tree/main/crates/soth-cli): operator CLI · Entrypoint for install, enrollment, config, proxy lifecycle, events, and updates. · `crates/soth-cli`
- [soth-proxy](https://github.com/hugger-mugger/soth/tree/main/crates/soth-proxy): interceptor daemon · Long-running local proxy that terminates TLS for selected domains and enforces traffic decisions. · `crates/soth-proxy`
- [gating pipeline](https://github.com/hugger-mugger/soth/tree/main/crates/soth-proxy/src/gating): policy stages · Staged request gating: TLS, app-origin, whitelist, blacklist, app-type, and host-origin checks. · `crates/soth-proxy/src/gating`
- [sessions](https://github.com/hugger-mugger/soth/tree/main/crates/soth-proxy/src/session): local state · Session store and lane tracking for proxy-side request/response state. · `crates/soth-proxy/src/session`
- [observability](https://github.com/hugger-mugger/soth/tree/main/crates/soth-proxy/src/observability): redaction/tracing · Local observability modules for redaction, tracing, and operational visibility. · `crates/soth-proxy/src/observability`
- [runtime core](https://github.com/hugger-mugger/soth/blob/main/crates/soth-proxy/src/runtime.rs): network handler · Request handling, streaming, response shaping, and proxy execution plumbing. · `crates/soth-proxy/src/runtime.rs`

### Shared crates

Common domain model, policy, parsing, and bundle logic.

- [soth-core](https://github.com/hugger-mugger/soth/tree/main/crates/soth-core): domain core · Shared identities, requests, sessions, observations, policy, providers, crypto, and normalized events. · `crates/soth-core`
- [api-types](https://github.com/hugger-mugger/soth/tree/main/crates/soth-api-types): wire contract · Serialized API shapes and conversions shared across proxy, sync, bindings, and cloud-facing code. · `crates/soth-api-types`
- [soth-policy](https://github.com/hugger-mugger/soth/tree/main/crates/soth-policy): policy engine · Standalone synchronous policy evaluation layer. · `crates/soth-policy`
- [soth-classify](https://github.com/hugger-mugger/soth/tree/main/crates/soth-classify): classification pipeline · Multi-stage inference for use cases, volatility, anomalies, policy signals, and telemetry enrichment. · `crates/soth-classify`
- [soth-detect](https://github.com/hugger-mugger/soth/tree/main/crates/soth-detect): detection engine · Deterministic helpers for sensitive data, code, streaming parse, and replay logic. · `crates/soth-detect`
- [soth-bundle](https://github.com/hugger-mugger/soth/tree/main/crates/soth-bundle): bundle loader · Signed bundle artifact loading, verification, entity indexing, and watcher/runtime support. · `crates/soth-bundle`
- [soth-telemetry](https://github.com/hugger-mugger/soth/tree/main/crates/soth-telemetry): sqlite store · Local SQLite-backed event store used as the system of record in standalone mode. · `crates/soth-telemetry`

### Cloud sync

Optional managed backend integration and replay path.

- [soth-sync](https://github.com/hugger-mugger/soth/tree/main/crates/soth-sync): cloud bridge · Enrollment, config/registry pulls, body uploads, heartbeat, retry, and telemetry replay to SOTH Cloud. · `crates/soth-sync`

### Bindings

Native SDKs and ecosystem wrappers.

- [soth-node](https://github.com/hugger-mugger/soth/tree/main/bindings/soth-node): node binding · Node native binding plus instrumentation and integration wrappers. · `bindings/soth-node`
- [soth-py](https://github.com/hugger-mugger/soth/tree/main/bindings/soth-py): python binding · Python native binding plus instrumentation and integrations. · `bindings/soth-py`
- [soth-go](https://github.com/hugger-mugger/soth/tree/main/sdks/soth-go): go sdk · Go SDK and WASM bridge wrapper. · `sdks/soth-go`
- [soth-edge](https://github.com/hugger-mugger/soth/tree/main/bindings/soth-edge): edge wrapper · Browser/edge wrapper for ecosystem-specific integration. · `bindings/soth-edge`

### Extensions

Agent-tool integration and historical import layers.

- [extensions/code](https://github.com/hugger-mugger/soth/tree/main/extensions/code): agent adapters · Parses and adapts events from coding tools into a common hook/event model. · `extensions/code`
- [extensions/historian](https://github.com/hugger-mugger/soth/tree/main/extensions/historian): historical import · Backfills and normalizes historical records from JSON, JSONL, or SQLite sources. · `extensions/historian`

## Connections

- soth-cli → soth-proxy: manages · Starts, stops, diagnoses, and updates the local proxy daemon.
- soth-cli → soth-bundle: installs rules · Downloads and applies bundle artifacts and update payloads.
- soth-cli → soth-sync: enrolls · Uses cloud enrollment and login flows when the managed backend is enabled.
- soth-proxy → gating pipeline: enforces · Routes traffic through staged allow/block handling.
- soth-proxy → sessions: tracks · Maintains local request/session state.
- soth-proxy → observability: emits · Feeds redaction and tracing pipelines.
- soth-proxy → runtime core: processes · Handles interception, streaming, and response lifecycle.
- gating pipeline → soth-policy: evaluates · Uses policy logic to decide traffic outcomes.
- gating pipeline → soth-bundle: loads rules · Consumes gating data and signed bundle content.
- runtime core → soth-core: uses model · Depends on shared request, session, identity, and event primitives.
- soth-policy → soth-core: shares domain · Builds on the common policy and request model.
- soth-classify → soth-core: consumes events · Classifies normalized observations and request context.
- soth-classify → soth-detect: feeds signals · Uses detection outputs and replay helpers for enrichment.
- soth-detect → soth-bundle: reads bundles · Loads detection bundles and registry-derived caches.
- soth-telemetry → soth-core: stores events · Persists normalized telemetry and captured observations.
- soth-sync → api-types: speaks contract · Uses shared API shapes for cloud exchange.
- soth-sync → soth-telemetry: replays · Uploads local telemetry and outbox contents.
- soth-sync → soth-bundle: pulls config · Fetches registry and bundle artifacts from cloud services.
- soth-node → soth-core: binds core · Exposes the Rust implementation to Node consumers.
- soth-py → soth-core: binds core · Exposes the Rust implementation to Python consumers.
- soth-go → soth-core: binds core · Wraps the shared engine for Go consumers.
- soth-edge → api-types: wraps contract · Implements edge/browser-facing wrappers around shared API shapes.
- extensions/code → soth-core: normalizes · Maps tool-specific events into the common event model.
- extensions/historian → soth-telemetry: imports · Backfills local records into the telemetry/store layer.