Ridge Runtime Architecture

This page maps the runtime shared by Ridge DB and Ridge Admin. It is derived from the current ridged, ridge_pgwire, ridge_sql, ridge, and ridge-admin implementations rather than from a generic database template.

Open the interactive Archify diagram

The interactive map provides searchable components, directed route tracing, guided views for the main query path, remote SSH, durability, and security, dark/light themes, keyboard navigation, and SVG or raster export.

System map

Browser
  │ HTTP on loopback
  ▼
Ridge Admin security gate
  │ authenticated API + workspace
  ▼
Ridge Admin services ──► four-connection pgwire pool
                              │
                              ├── local pgwire ─────────────────────┐
                              │                                     │
                              └── verified SSH direct-tcpip ────────┤
                                                                    ▼
                                                       ridged pgwire runtime
                                                                    │
                                                                    ▼
                                                       Ridge SQL session
                                                                    │
                                                                    ▼
                                                       Ridge core / MVCC
                                                                    │
                                                                    ▼
                                                       B+Trees + WAL + rows

The primary path is intentionally narrow. The browser never receives a database socket or SSH credential. Both local and remote profiles converge on the same pgwire, SQL, transaction, and storage contracts.

Runtime components

Component	Responsibility	Canonical implementation
Browser UI	Object explorer, SQL workspaces, data editing, operations	`grove/apps/ridge-admin/static/`
HTTP security gate	One-time launch exchange, session cookie, CSRF, Host and Origin checks	`grove/apps/ridge-admin/src/main.sd`, `src/lib.sd`
Admin services	Profiles, metadata, SQL execution, editing, export, diagnostics	`grove/apps/ridge-admin/src/main.sd`
Pgwire pool	Four owned connections, workspace leases, transactions, cancellation	`grove/apps/ridge-admin/src/lib.sd`, `grove/libs/pg`
SSH transport	Known-host verification, authentication, `direct-tcpip`, reconnect and cancel channels	`grove/libs/ssh`, `grove/apps/ridge-admin/src/main.sd`
`ridged` pgwire	Loopback listener, TLS/password auth, reactor shards, queues, cancellation, storage coordination	`grove/libs/ridge_pgwire`
Ridge SQL	Parsing, classification, planning, prepared execution, result and work limits	`grove/libs/ridge_sql`
Ridge core	Catalog, schemas, MVCC, transactions, indexes, conflicts, vacuum, backup and recovery	`grove/libs/ridge`
Durable storage	Recursive B+Trees, logical CRC-32 WAL, generation-2 row/schema codec	`grove/libs/btree_store`, `grove/libs/wal`, `grove/libs/rowcodec`

Primary query flow

Ridge Admin binds its HTTP server to 127.0.0.1 and gives the browser a one-time fragment token.
The browser exchanges the fragment for an HTTP-only session cookie and receives a per-session CSRF token.
The HTTP dispatcher validates request size, route, method, Host, Origin, session, CSRF, and content type before invoking a service.
A SQL workspace leases one owned connection from the four-connection pool.
Local profiles connect to ridged on loopback. Remote profiles put the same client protocol through a verified SSH direct-tcpip channel without opening a forwarding listener.
A ridged reactor shard validates startup, TLS/authentication, protocol frames, prepared statements, portal state, output pressure, and cancellation metadata.
The storage coordinator routes the bounded request to a Ridge SQL session.
Ridge SQL parses and plans a supported statement, enforces result/work limits, and executes through the Ridge core.
Ridge core applies MVCC visibility, locking, constraints, indexes, WAL publication, B+Tree changes, checksums, and fsync as required.
Results return through pgwire. Ridge Admin converts bounded protocol frames to JSON or CSV and returns them to the browser.

An interrupted write is never replayed automatically. Ridge Admin marks an ambiguous outcome as uncertain and requires operator verification.

Concurrency model

Persistent ridged requires at least two Seed workers. It divides part of the worker set into nonblocking reactor shards and keeps capacity for storage work. Each shard owns its listener, connection slab, protocol state, prepared plans, output backpressure, cancellation token, and a read-only snapshot reader. Bounded channels connect shards to the storage coordinator.

The coordinator preserves transaction ownership, commit grouping, shutdown drain, and cancellation routing. Reads may use independent snapshots; durable writes still pass through Ridge conflict detection and publication rules.

Ridge Admin uses structured spawn for bounded HTTP connections and an owned SSH manager. Server state owns the pool, workspace leases, active-query cancellation, reconnection state, and deterministic cleanup.

External dependencies

Dependency	Runtime use	Boundary
OpenSSL 3	Native `ridged` server TLS context and connection I/O	Explicit native backend linked with `libssl` and `libcrypto`
Hosted Seed runtime	Sockets, event reactor, signals, task scheduler, entropy, time, files, locks, and fsync	Platform-specific runtime ABI
Operating-system filesystem	Database files, WAL, catalog, indexes, snapshots, backups, logs, profile store	Operator- or user-controlled absolute roots
Browser	Presentation, short-lived view state, local drafts	Untrusted relative to backend authority
SSH server and agent	Host identity, authentication, encrypted transport	Verified before database traffic

Ridge does not depend on a PostgreSQL server. PostgreSQL compatibility is limited to the documented client-side wire subset.

Security boundaries

Browser to Ridge Admin

The listener is loopback-only.
The launch secret is carried in the URL fragment, not a query parameter.
The one-time exchange produces an HTTP-only, SameSite session cookie.
Mutations require an exact loopback Origin and a per-session CSRF token.
Host, content type, header/body size, and route/method combinations are validated before dispatch.
CSP, no-store, nosniff, and restrictive referrer behavior reduce browser exposure.

Ridge Admin to database

The backend owns all sockets, transactions, secrets, and cleanup.
Profiles do not persist database passwords, SSH passwords, or key passphrases.
Credentials retained for cancellation or one reconnect are bounded and zeroized from process memory.
A workspace stays pinned to its transaction and connection state.
Disconnects do not cause query replay.

SSH boundary

Strict known-host verification is the default; explicit accept-new is a first-contact policy, not a changed-host bypass.
Native direct-tcpip channels reach the remote loopback ridged endpoint.
No local TCP forwarding listener is opened.
Query cancellation uses a separate verified SSH channel.

`ridged` boundary

The service binds only to 127.0.0.1.
TLS and password authentication are operator-configured; a cleartext password challenge is accepted only inside TLS.
The current server exposes one configured database/user plus a bounded read-only role, not a PostgreSQL role catalog.
Messages, prepared statements, portals, queues, result buffers, and connection counts have checked limits.
Unsupported SQL and protocol shapes fail explicitly.

Storage boundary

Database and backup roots are absolute and operator controlled.
Names and paths reject traversal; restore refuses an existing target.
WAL frames and backup files are checksummed.
Commit acknowledgment follows the documented durability boundary.
Recovery replays committed state idempotently and reconstructs derived indexes and heads.
Direct file editing bypasses invariants and is unsupported.

Failure containment

Failure	Containment behavior
Malformed HTTP or oversized body	Typed HTTP error before service dispatch
Invalid pgwire frame or unsupported protocol	Bounded protocol/SQLSTATE error and connection cleanup
Queue saturation or timeout	Explicit rejection; no unbounded queue growth
Client cancellation	Routed to the owning shard/session before publication where possible
Network interruption during write	Uncertain result; no automatic replay
Transaction conflict	Deterministic conflict without partial publication
Process crash	Committed logical WAL replay; unpublished work remains invisible
Corrupt WAL or backup	Checksum/integrity failure instead of silent acceptance
Restore collision or traversal	Offline restore rejects the target

Architectural non-goals

This map does not imply a remote multi-user Ridge Admin service, general PostgreSQL administration, replication, clustering, sharding, a public database listener, SCRAM, certificate identities, full PostgreSQL catalogs, or unrestricted driver/ORM compatibility.

Diagram provenance

The interactive artifact was produced with Archify 2.12 in Architecture mode using the Classic static presentation and the Showcase composition gate. Its typed source is seed/docs/diagrams/ridge-runtime.architecture.json.

The map is evidence-backed by repository inspection, but it intentionally does not embed private repository paths as clickable source evidence. The source files listed above remain the review anchors.