Architecture

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

High-Level Overview

┌─────────────────────────────────────────────────────────────┐
│                    ADAPTER LAYER                             │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────────┐   │
│  │ HTTP API│  │   MCP   │  │  Tauri  │  │  Embedded   │   │
│  └────┬────┘  └────┬────┘  └────┬────┘  └──────┬──────┘   │
│       └────────────┴─────────────┴─────────────┘           │
│                          │                                   │
│                          ▼                                   │
│               ┌─────────────────┐                           │
│               │relay-core-runtime│                          │
│               │(State, Events)   │                          │
│               └────────┬─────────┘                           │
│                        │                                      │
└────────────────────────┼────────────────────────────────────┘
                         │
     ┌───────────────────┼───────────────────┐
     ▼                   ▼                   ▼
┌──────────┐  ┌──────────────┐  ┌──────────────┐
│   lib    │  │   storage    │  │   script     │
│ (engine) │  │  (SQLite)    │  │  (Deno/V8)   │
└──────────┘  └──────────────┘  └──────────────┘

Core Crates

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 (Beta)

MCP adapter. Exposes tools for AI agents to observe and control the proxy programmatically.

relay-core-cli (Beta)

Standalone CLI binary with TUI. Provides terminal interface for running the proxy and managing rules/flows.

relay-core-lib (Internal)

Core interception engine. Handles HTTP/HTTPS proxy, WebSocket, MITM with TLS, and the rule engine.

relay-core-storage (Internal)

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

relay-core-script (Internal)

Deno/V8 JavaScript runtime for dynamic request/response modification.

Data Flow

1. Client connects to proxy (e.g., curl --proxy http://localhost:8080 https://example.com)
2. relay-core-lib captures the request
3. Rules are evaluated against the flow
4. For HTTPS: MITM intercepts and decrypts
5. Flow is stored in relay-core-storage
6. Events are published via CoreState event bus
7. Adapters (HTTP API, MCP, CLI) can query/control via CoreState

Configuration

RelayCore reads configuration from ~/.relay-core/config.toml:

[proxy]
port = 8080
bind_address = "0.0.0.0"

[storage]
sqlite_path = "~/.relay-core/flows.db"
max_flows = 10000

[mcp]
enabled = true
port = 25519