Architecture

RelayCore is organized as a Rust workspace with multiple crates, each with a specific responsibility.

High-Level Overview

ADAPTER LAYER public crates PUBLIC relay-core-http REST + SSE PUBLIC relay-core-probe MCP · AI PUBLIC relay-core-tauri RelayCraft PUBLIC relay-core-cli CLI · TUI · embedded HTTP INTERNAL relay-core-api Flow · Rule · Policy · Event PUBLIC relay-core-runtime CoreState lifecycle · rule store · event bus · proxy spawn ENGINE internal crates INTERNAL relay-core-lib MITM · HTTP/HTTPS · WebSocket · TLS · rule execution interceptor chain: Script → Rule → Metrics → adapter INTERNAL relay-core-storage SQLite optional persist · flows · audit INTERNAL relay-core-script Deno/V8 (optional) feature "script"

Core Crates

relay-core-api (Internal)

Shared contracts (Flow, Rule, Policy, Event). Crates exchange data through it; users should use runtime re-exports.

relay-core-runtime (Public)

The main API crate. Provides CoreState for state orchestration, proxy lifecycle management, rule evaluation, and event distribution.

relay-core-http (Public)

REST + SSE adapter. Exposes CoreState via HTTP with JSON API and Server-Sent Events for real-time updates.

relay-core-probe (GA)

MCP adapter (npm: @relay-core/mcp). Standalone relay-core-probe binary embeds the proxy and exposes MCP tools.

relay-core-cli (GA)

Standalone CLI and TUI. relay-core-cli run starts the proxy plus embedded REST+SSE (--api-port) and a control API.

relay-core-lib (Internal)

Traffic engine: HTTP/HTTPS proxy, WebSocket, MITM/TLS, rule execution. Runtime wires Script / Rule interceptors into lib's chain.

relay-core-storage (Internal)

SQLite persistence. Handles flow storage with LRU cache and audit logging.

relay-core-script (Internal)

Deno/V8 scripting (optional feature). Injected by runtime into lib's interceptor chain — not a parallel proxy path.

Data Flow

  1. Client connects to the proxy (e.g., curl --proxy http://localhost:8080 https://example.com)
  2. relay-core-lib captures and forwards traffic
  3. Interceptor chain runs: Script → Rule → Metrics → host adapter (order from runtime)
  4. For HTTPS: MITM intercepts and decrypts
  5. Flows go to runtime in-memory LRU; optional persistence via relay-core-storage when configured
  6. Events published on the CoreState bus (flows, audit)
  7. Adapters (HTTP, MCP, CLI, Tauri) query and control through CoreState

Configuration

Paths and CA settings use environment variables and CLI flags — see Configuration. Default data directory: ~/.relay-core.