Architecture
How the server, engine, Postgres, and object storage fit together.
Eddytor is four moving parts: a server, one or more engines, a Postgres database, and your object storage. Understanding the split makes deployment, scaling, and troubleshooting straightforward.
The parts
| Part | Role |
|---|---|
| Server | The control plane. Serves the REST + gRPC API, the MCP endpoint, auth, and the optional Web UI's backend. Runs database migrations at boot. |
| Engine | The data plane. Reads and writes Delta Lake tables and runs queries. Stateless - scales out horizontally under load. |
| Postgres | Eddytor's own metadata: users, organisations, storage connections, API keys, encrypted secrets. Not your table data. |
| Object storage | Your S3 / GCS / Azure Blob buckets, where the Delta tables actually live. Eddytor connects to it; it never copies data elsewhere. |
┌──────────┐ gRPC (h2c) ┌──────────┐
client ───▶│ server │────────────────────▶│ engine │───▶ object storage
CLI/REST │ (control)│◀────────────────────│ (data, │ (your Delta tables)
MCP/UI └────┬─────┘ │ scales) │
│ └──────────┘
▼
┌──────────┐
│ Postgres │ (Eddytor metadata, not your data)
└──────────┘How a request flows
- A client (CLI, REST, MCP, or the Web UI) calls the server.
- The server authenticates, applies permissions, and reads/writes its metadata in Postgres.
- For anything touching table data, the server dispatches to an engine.
- The engine reads/writes the Delta table directly in your object storage and streams results back.
Why the engine is separate
The engine is stateless and does the heavy I/O and query work, so you scale it independently of the server. On Kubernetes you just add replicas; the server fans work out across them. See Scaling the engine.
Networking & TLS
Eddytor's binaries speak plaintext internally - the server↔engine hop is h2c (HTTP/2 cleartext), and the HTTP/gRPC listeners are unencrypted. TLS is terminated at the edge by a reverse proxy or load balancer in front of the server (or a service mesh in Kubernetes). Trust the local network, encrypt at the boundary - there's no internal certificate mesh to manage. See TLS termination & reverse proxy.
Bulk queries use a separate endpoint
Most operations go over the REST/gRPC API on the server. Bulk SQL queries
(eddytor query) use Flight SQL on the server's Flight proxy - a different
port (8082) from the REST API (8080). Keep this in mind when configuring the
CLI and firewalls; see Interfaces.
Next
- Editions & images - pick the right build.
- Deploy & Run - Compose and Kubernetes topologies.