# superdurable/dex architecture

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

- Interactive diagram: https://gitdiagram.com/superdurable/dex
- Repository: https://github.com/superdurable/dex

## Overview

Dex is a durable-execution platform: applications define flows and run workers through language SDKs, while clients start and interact with flow instances through the server. The server dispatches Step and RPC tasks to workers and builds on Temporal. SDKs provide flow primitives, execution context, value mapping, and worker dispatch. The repository also includes a web workspace and CLI tooling. The main workflow links are documented in the README; relationships among unsampled subsystems are omitted rather than inferred.

Main entry points: [`server/cmd/server/main.go`](https://github.com/superdurable/dex/blob/main/server/cmd/server/main.go) (Dex Server), [`sdk-python/dex/async_client.py`](https://github.com/superdurable/dex/blob/main/sdk-python/dex/async_client.py) (Python Client), [`sdk-go/dex/client.go`](https://github.com/superdurable/dex/blob/main/sdk-go/dex/client.go) (Go SDK Client), [`sdk-python/dex/flow.py`](https://github.com/superdurable/dex/blob/main/sdk-python/dex/flow.py) (Python Flow Definitions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_sdk["Application SDKs"]
  node_go_sdk["Go SDK Client<br/>[client.go]"]
  node_py_flow["Python Flow Definitions<br/>[flow.py]"]
  node_py_context["Python Primitives<br/>[context.py]"]
  node_py_client["Python Client<br/>[async_client.py]"]
  node_py_dispatch["Python Worker Dispatcher"]
  node_py_mapping["Python Value Mapping<br/>[_value_mapper.py]"]
  node_ts_client["TypeScript Client<br/>[client.ts]"]
  node_java_worker["Java Worker Service"]
end

subgraph group_runtime["Execution Runtime"]
  node_server["Dex Server<br/>[main.go]"]
  node_interpreter["Flow Interpreter<br/>[queryHandler.go]"]
end

subgraph group_tools["User Interfaces"]
  node_web_app["Web Workspace<br/>[App.tsx]"]
  node_web_api["Web API<br/>[handlers.go]"]
  node_cli["Dex CLI<br/>[main.go]"]
  node_cli_commands["CLI Commands<br/>[app.go]"]
end

subgraph group_protocol["Protocol and Storage"]
  node_protobuf["Service Protocol<br/>[dex.proto]"]
  node_attribute_store[("Attribute Store Manager<br/>[manager.go]")]
  node_blob_cache[("Blob Cache<br/>[cache.go]")]
end

node_developer(("Application Developer"))
node_temporal["Temporal"]

node_developer -->|"defines flows"| node_py_flow
node_developer -->|"uses client"| node_go_sdk
node_developer -->|"uses client"| node_py_client
node_developer -->|"uses client"| node_ts_client
node_py_flow -->|"uses primitives"| node_py_context
node_py_client -->|"maps values"| node_py_mapping
node_py_dispatch -->|"maps values"| node_py_mapping
node_py_client -->|"starts and interacts"| node_server
node_go_sdk -->|"starts and interacts"| node_server
node_ts_client -->|"starts and interacts"| node_server
node_server -->|"dispatches tasks"| node_py_dispatch
node_server -->|"dispatches tasks"| node_java_worker
node_server -.->|"runs flow logic"| node_interpreter
node_server -->|"extends"| node_temporal
node_server -->|"syncs attributes"| node_attribute_store
node_server -->|"offloads payloads"| node_blob_cache
node_py_client -.->|"uses protocol"| node_protobuf
node_web_app -.->|"uses API"| node_web_api
node_cli -->|"runs commands"| node_cli_commands

click node_go_sdk "https://github.com/superdurable/dex/blob/main/sdk-go/dex/client.go"
click node_py_flow "https://github.com/superdurable/dex/blob/main/sdk-python/dex/flow.py"
click node_py_context "https://github.com/superdurable/dex/blob/main/sdk-python/dex/context.py"
click node_py_client "https://github.com/superdurable/dex/blob/main/sdk-python/dex/async_client.py"
click node_py_dispatch "https://github.com/superdurable/dex/blob/main/sdk-python/dex/_worker_dispatcher.py"
click node_py_mapping "https://github.com/superdurable/dex/blob/main/sdk-python/dex/_value_mapper.py"
click node_ts_client "https://github.com/superdurable/dex/blob/main/sdk-typescript/src/client.ts"
click node_java_worker "https://github.com/superdurable/dex/blob/main/sdk-java/src/main/java/io/superdurable/dex/JavaWorkerService.java"
click node_server "https://github.com/superdurable/dex/blob/main/server/cmd/server/main.go"
click node_interpreter "https://github.com/superdurable/dex/blob/main/server/service/interpreter/queryHandler.go"
click node_web_app "https://github.com/superdurable/dex/blob/main/web/app/App.tsx"
click node_web_api "https://github.com/superdurable/dex/blob/main/web/api/handlers.go"
click node_cli "https://github.com/superdurable/dex/blob/main/cli/cmd/dexcli/main.go"
click node_cli_commands "https://github.com/superdurable/dex/blob/main/cli/internal/command/app.go"
click node_protobuf "https://github.com/superdurable/dex/blob/main/protos/dex.proto"
click node_attribute_store "https://github.com/superdurable/dex/blob/main/server/service/common/attributestore/manager.go"
click node_blob_cache "https://github.com/superdurable/dex/blob/main/blob-cache-go/blobcache/cache.go"

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_go_sdk,node_py_flow,node_py_context,node_py_client,node_py_dispatch,node_py_mapping,node_ts_client,node_java_worker toneBlue
class node_server,node_interpreter toneAmber
class node_web_app,node_web_api,node_cli,node_cli_commands toneMint
class node_protobuf,node_attribute_store,node_blob_cache toneRose
class node_developer,node_temporal toneIndigo
```

## Components

### Application SDKs

- [Go SDK Client](https://github.com/superdurable/dex/blob/main/sdk-go/dex/client.go): `sdk-go/dex/client.go`
- [Python Flow Definitions](https://github.com/superdurable/dex/blob/main/sdk-python/dex/flow.py): `sdk-python/dex/flow.py`
- [Python Primitives](https://github.com/superdurable/dex/blob/main/sdk-python/dex/context.py): `sdk-python/dex/context.py`
- [Python Client](https://github.com/superdurable/dex/blob/main/sdk-python/dex/async_client.py): `sdk-python/dex/async_client.py`
- [Python Worker Dispatcher](https://github.com/superdurable/dex/blob/main/sdk-python/dex/_worker_dispatcher.py): `sdk-python/dex/_worker_dispatcher.py`
- [Python Value Mapping](https://github.com/superdurable/dex/blob/main/sdk-python/dex/_value_mapper.py): `sdk-python/dex/_value_mapper.py`
- [TypeScript Client](https://github.com/superdurable/dex/blob/main/sdk-typescript/src/client.ts): `sdk-typescript/src/client.ts`
- [Java Worker Service](https://github.com/superdurable/dex/blob/main/sdk-java/src/main/java/io/superdurable/dex/JavaWorkerService.java): `sdk-java/src/main/java/io/superdurable/dex/JavaWorkerService.java`

### Execution Runtime

- [Dex Server](https://github.com/superdurable/dex/blob/main/server/cmd/server/main.go): `server/cmd/server/main.go`
- [Flow Interpreter](https://github.com/superdurable/dex/blob/main/server/service/interpreter/queryHandler.go): `server/service/interpreter/queryHandler.go`

### User Interfaces

- [Web Workspace](https://github.com/superdurable/dex/blob/main/web/app/App.tsx): `web/app/App.tsx`
- [Web API](https://github.com/superdurable/dex/blob/main/web/api/handlers.go): `web/api/handlers.go`
- [Dex CLI](https://github.com/superdurable/dex/blob/main/cli/cmd/dexcli/main.go): `cli/cmd/dexcli/main.go`
- [CLI Commands](https://github.com/superdurable/dex/blob/main/cli/internal/command/app.go): `cli/internal/command/app.go`

### Protocol and Storage

- [Service Protocol](https://github.com/superdurable/dex/blob/main/protos/dex.proto): `protos/dex.proto`
- [Attribute Store Manager](https://github.com/superdurable/dex/blob/main/server/service/common/attributestore/manager.go): `server/service/common/attributestore/manager.go`
- [Blob Cache](https://github.com/superdurable/dex/blob/main/blob-cache-go/blobcache/cache.go): `blob-cache-go/blobcache/cache.go`

### Other components

- **Application Developer**
- **Temporal**

## Connections

- Application Developer → Python Flow Definitions: defines flows
- Application Developer → Go SDK Client: uses client
- Application Developer → Python Client: uses client
- Application Developer → TypeScript Client: uses client
- Python Flow Definitions → Python Primitives: uses primitives (evidence: `sdk-python/dex/flow.py`)
- Python Client → Python Value Mapping: maps values (evidence: `sdk-python/dex/async_client.py`)
- Python Worker Dispatcher → Python Value Mapping: maps values (evidence: `sdk-python/dex/_worker_dispatcher.py`)
- Python Client → Dex Server: starts and interacts
- Go SDK Client → Dex Server: starts and interacts
- TypeScript Client → Dex Server: starts and interacts
- Dex Server → Python Worker Dispatcher: dispatches tasks
- Dex Server → Java Worker Service: dispatches tasks
- Dex Server → Flow Interpreter: runs flow logic
- Dex Server → Temporal: extends
- Dex Server → Attribute Store Manager: syncs attributes
- Dex Server → Blob Cache: offloads payloads
- Python Client → Service Protocol: uses protocol
- Web Workspace → Web API: uses API
- Dex CLI → CLI Commands: runs commands (evidence: `cli/cmd/dexcli/main.go`)
