# shroudb/shroudb-sdk-ruby architecture

> Architecture diagram of the GitHub repository shroudb/shroudb-sdk-ruby, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shroudb/shroudb-sdk-ruby
- Repository: https://github.com/shroudb/shroudb-sdk-ruby

## Overview

ShrouDB is a unified Ruby SDK for database, encryption, identity, and other ShrouDB engines. A caller configures a Client for Moat or direct engine connections, invokes a namespaced engine command, and receives parsed results or a typed response. The client selects transports; engine namespaces serialize commands, while transport implementations handle HTTP or RESP3 communication. The README and sampled sources confirm several engine capabilities and the multi-engine routing model; implementation details for unsampled engines are limited to their modules and paths.

Main entry points: [`lib/shroudb/client.rb`](https://github.com/shroudb/shroudb-sdk-ruby/blob/main/lib/shroudb/client.rb) (Unified Client), [`lib/shroudb/transport/interface.rb`](https://github.com/shroudb/shroudb-sdk-ruby/blob/main/lib/shroudb/transport/interface.rb) (Transport Interface), [`lib/shroudb/transport/resp3.rb`](https://github.com/shroudb/shroudb-sdk-ruby/blob/main/lib/shroudb/transport/resp3.rb) (RESP3 Transport), [`lib/shroudb/engines/shroudb.rb`](https://github.com/shroudb/shroudb-sdk-ruby/blob/main/lib/shroudb/engines/shroudb.rb) (Encrypted KV)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Client Routing"]
  node_client["Unified Client<br/>[client.rb]"]
end

subgraph group_engines["Engine Commands"]
  node_shroudb["Encrypted KV<br/>[shroudb.rb]"]
  node_cipher["Encryption Service<br/>[cipher.rb]"]
  node_sigil["Credential Envelopes<br/>[sigil.rb]"]
  node_veil["Veil Engine<br/>[veil.rb]"]
  node_sentry["Sentry Engine<br/>[sentry.rb]"]
  node_forge["Forge Engine<br/>[forge.rb]"]
  node_keep["Keep Engine<br/>[keep.rb]"]
  node_courier["Courier Engine<br/>[courier.rb]"]
  node_chronicle["Chronicle Engine<br/>[chronicle.rb]"]
  node_stash["Stash Engine<br/>[stash.rb]"]
  node_scroll["Event Log<br/>[scroll.rb]"]
end

subgraph group_transport["Transport Layer"]
  node_interface["Transport Interface<br/>[interface.rb]"]
  node_resp3["RESP3 Transport<br/>[resp3.rb]"]
  node_http["HTTP Transport<br/>[http.rb]"]
  node_pool["Connection Pool<br/>[resp3.rb]"]
end

subgraph group_models["Response Models"]
  node_shroudb_types["KV Responses<br/>[shroudb.rb]"]
  node_cipher_types["Cipher Responses<br/>[cipher.rb]"]
  node_sigil_types["Sigil Responses<br/>[sigil.rb]"]
end

node_caller(("Ruby Application"))
node_moat{{"Moat Gateway"}}
node_engine_servers{{"Engine Servers"}}

node_caller -->|"configures and calls"| node_client
node_client -->|"routes commands"| node_shroudb
node_client -->|"routes commands"| node_cipher
node_client -->|"routes commands"| node_sigil
node_client -->|"routes commands"| node_veil
node_client -->|"routes commands"| node_sentry
node_client -->|"routes commands"| node_forge
node_client -->|"routes commands"| node_keep
node_client -->|"routes commands"| node_courier
node_client -->|"routes commands"| node_chronicle
node_client -->|"routes commands"| node_stash
node_client -->|"routes commands"| node_scroll
node_client -->|"creates HTTP transport"| node_http
node_client -->|"creates RESP3 transport"| node_resp3
node_shroudb -->|"executes commands"| node_interface
node_cipher -->|"executes commands"| node_interface
node_sigil -->|"executes commands"| node_interface
node_veil -->|"executes commands"| node_interface
node_sentry -->|"executes commands"| node_interface
node_forge -->|"executes commands"| node_interface
node_keep -->|"executes commands"| node_interface
node_courier -->|"executes commands"| node_interface
node_chronicle -->|"executes commands"| node_interface
node_stash -->|"executes commands"| node_interface
node_scroll -->|"executes commands"| node_interface
node_interface -->|"implemented by"| node_resp3
node_interface -->|"implemented by"| node_http
node_resp3 -->|"uses connections"| node_pool
node_http -->|"POSTs commands"| node_moat
node_resp3 -->|"sends RESP3 commands"| node_engine_servers
node_shroudb -->|"builds responses"| node_shroudb_types
node_cipher -->|"builds responses"| node_cipher_types
node_sigil -->|"builds responses"| node_sigil_types

click node_client "https://github.com/shroudb/shroudb-sdk-ruby/blob/main/lib/shroudb/client.rb"
click node_shroudb "https://github.com/shroudb/shroudb-sdk-ruby/blob/main/lib/shroudb/engines/shroudb.rb"
click node_cipher "https://github.com/shroudb/shroudb-sdk-ruby/blob/main/lib/shroudb/engines/cipher.rb"
click node_sigil "https://github.com/shroudb/shroudb-sdk-ruby/blob/main/lib/shroudb/engines/sigil.rb"
click node_veil "https://github.com/shroudb/shroudb-sdk-ruby/blob/main/lib/shroudb/engines/veil.rb"
click node_sentry "https://github.com/shroudb/shroudb-sdk-ruby/blob/main/lib/shroudb/engines/sentry.rb"
click node_forge "https://github.com/shroudb/shroudb-sdk-ruby/blob/main/lib/shroudb/engines/forge.rb"
click node_keep "https://github.com/shroudb/shroudb-sdk-ruby/blob/main/lib/shroudb/engines/keep.rb"
click node_courier "https://github.com/shroudb/shroudb-sdk-ruby/blob/main/lib/shroudb/engines/courier.rb"
click node_chronicle "https://github.com/shroudb/shroudb-sdk-ruby/blob/main/lib/shroudb/engines/chronicle.rb"
click node_stash "https://github.com/shroudb/shroudb-sdk-ruby/blob/main/lib/shroudb/engines/stash.rb"
click node_scroll "https://github.com/shroudb/shroudb-sdk-ruby/blob/main/lib/shroudb/engines/scroll.rb"
click node_interface "https://github.com/shroudb/shroudb-sdk-ruby/blob/main/lib/shroudb/transport/interface.rb"
click node_resp3 "https://github.com/shroudb/shroudb-sdk-ruby/blob/main/lib/shroudb/transport/resp3.rb"
click node_http "https://github.com/shroudb/shroudb-sdk-ruby/blob/main/lib/shroudb/transport/http.rb"
click node_pool "https://github.com/shroudb/shroudb-sdk-ruby/blob/main/lib/shroudb/transport/resp3.rb"
click node_shroudb_types "https://github.com/shroudb/shroudb-sdk-ruby/blob/main/lib/shroudb/types/shroudb.rb"
click node_cipher_types "https://github.com/shroudb/shroudb-sdk-ruby/blob/main/lib/shroudb/types/cipher.rb"
click node_sigil_types "https://github.com/shroudb/shroudb-sdk-ruby/blob/main/lib/shroudb/types/sigil.rb"

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_client toneBlue
class node_shroudb,node_cipher,node_sigil,node_veil,node_sentry,node_forge,node_keep,node_courier,node_chronicle,node_stash,node_scroll toneAmber
class node_interface,node_resp3,node_http,node_pool,node_engine_servers toneMint
class node_shroudb_types,node_cipher_types,node_sigil_types toneRose
class node_caller,node_moat toneIndigo
```

## Components

### Client Routing

- [Unified Client](https://github.com/shroudb/shroudb-sdk-ruby/blob/main/lib/shroudb/client.rb): `lib/shroudb/client.rb`

### Engine Commands

- [Encrypted KV](https://github.com/shroudb/shroudb-sdk-ruby/blob/main/lib/shroudb/engines/shroudb.rb): `lib/shroudb/engines/shroudb.rb`
- [Encryption Service](https://github.com/shroudb/shroudb-sdk-ruby/blob/main/lib/shroudb/engines/cipher.rb): `lib/shroudb/engines/cipher.rb`
- [Credential Envelopes](https://github.com/shroudb/shroudb-sdk-ruby/blob/main/lib/shroudb/engines/sigil.rb): `lib/shroudb/engines/sigil.rb`
- [Veil Engine](https://github.com/shroudb/shroudb-sdk-ruby/blob/main/lib/shroudb/engines/veil.rb): `lib/shroudb/engines/veil.rb`
- [Sentry Engine](https://github.com/shroudb/shroudb-sdk-ruby/blob/main/lib/shroudb/engines/sentry.rb): `lib/shroudb/engines/sentry.rb`
- [Forge Engine](https://github.com/shroudb/shroudb-sdk-ruby/blob/main/lib/shroudb/engines/forge.rb): `lib/shroudb/engines/forge.rb`
- [Keep Engine](https://github.com/shroudb/shroudb-sdk-ruby/blob/main/lib/shroudb/engines/keep.rb): `lib/shroudb/engines/keep.rb`
- [Courier Engine](https://github.com/shroudb/shroudb-sdk-ruby/blob/main/lib/shroudb/engines/courier.rb): `lib/shroudb/engines/courier.rb`
- [Chronicle Engine](https://github.com/shroudb/shroudb-sdk-ruby/blob/main/lib/shroudb/engines/chronicle.rb): `lib/shroudb/engines/chronicle.rb`
- [Stash Engine](https://github.com/shroudb/shroudb-sdk-ruby/blob/main/lib/shroudb/engines/stash.rb): `lib/shroudb/engines/stash.rb`
- [Event Log](https://github.com/shroudb/shroudb-sdk-ruby/blob/main/lib/shroudb/engines/scroll.rb): `lib/shroudb/engines/scroll.rb`

### Transport Layer

- [Transport Interface](https://github.com/shroudb/shroudb-sdk-ruby/blob/main/lib/shroudb/transport/interface.rb): `lib/shroudb/transport/interface.rb`
- [RESP3 Transport](https://github.com/shroudb/shroudb-sdk-ruby/blob/main/lib/shroudb/transport/resp3.rb): `lib/shroudb/transport/resp3.rb`
- [HTTP Transport](https://github.com/shroudb/shroudb-sdk-ruby/blob/main/lib/shroudb/transport/http.rb): `lib/shroudb/transport/http.rb`
- [Connection Pool](https://github.com/shroudb/shroudb-sdk-ruby/blob/main/lib/shroudb/transport/resp3.rb): `lib/shroudb/transport/resp3.rb`

### Response Models

- [KV Responses](https://github.com/shroudb/shroudb-sdk-ruby/blob/main/lib/shroudb/types/shroudb.rb): `lib/shroudb/types/shroudb.rb`
- [Cipher Responses](https://github.com/shroudb/shroudb-sdk-ruby/blob/main/lib/shroudb/types/cipher.rb): `lib/shroudb/types/cipher.rb`
- [Sigil Responses](https://github.com/shroudb/shroudb-sdk-ruby/blob/main/lib/shroudb/types/sigil.rb): `lib/shroudb/types/sigil.rb`

### Other components

- **Ruby Application**
- **Moat Gateway**
- **Engine Servers**

## Connections

- Ruby Application → Unified Client: configures and calls
- Unified Client → Encrypted KV: routes commands
- Unified Client → Encryption Service: routes commands
- Unified Client → Credential Envelopes: routes commands
- Unified Client → Veil Engine: routes commands
- Unified Client → Sentry Engine: routes commands
- Unified Client → Forge Engine: routes commands
- Unified Client → Keep Engine: routes commands
- Unified Client → Courier Engine: routes commands
- Unified Client → Chronicle Engine: routes commands
- Unified Client → Stash Engine: routes commands
- Unified Client → Event Log: routes commands
- Unified Client → HTTP Transport: creates HTTP transport
- Unified Client → RESP3 Transport: creates RESP3 transport
- Encrypted KV → Transport Interface: executes commands
- Encryption Service → Transport Interface: executes commands
- Credential Envelopes → Transport Interface: executes commands
- Veil Engine → Transport Interface: executes commands
- Sentry Engine → Transport Interface: executes commands
- Forge Engine → Transport Interface: executes commands
- Keep Engine → Transport Interface: executes commands
- Courier Engine → Transport Interface: executes commands
- Chronicle Engine → Transport Interface: executes commands
- Stash Engine → Transport Interface: executes commands
- Event Log → Transport Interface: executes commands
- Transport Interface → RESP3 Transport: implemented by
- Transport Interface → HTTP Transport: implemented by
- RESP3 Transport → Connection Pool: uses connections
- HTTP Transport → Moat Gateway: POSTs commands
- RESP3 Transport → Engine Servers: sends RESP3 commands
- Encrypted KV → KV Responses: builds responses
- Encryption Service → Cipher Responses: builds responses
- Credential Envelopes → Sigil Responses: builds responses