Deployment Modes

Understanding the platform’s deployment modes - Agent mode, CLI mode, and server mode.

Overview

The platform can run in different modes depending on your deployment type and use case.

Deployment Modes

1. Server Mode (Backend + Agents)

Architecture:

Backend Server ← → Agents (Workers)
     ↓
Metadata DB

How it works: * Backend server receives workflow requests (UI or API) * Backend coordinates execution across agents * Agents perform actual data transformation * Progress reported back to backend * Results stored in metadata database

Use cases: * Multi-user environments * Web UI needed * Scheduled workflows * Workflow history required

Deployment: Docker Compose or Kubernetes

2. CLI Mode (Standalone)

Architecture:

TDK CLI → Direct DB-to-DB transformation

How it works: * Single process executes entire workflow * Reads configuration from YAML files * No backend server needed * No metadata database * Outputs logs to stdout

Use cases: * CI/CD pipelines * Automated scripts * Simple transformations * No UI needed

Deployment: Standalone binary or Docker container

See: CLI Overview

3. Hybrid Mode

Architecture:

Backend Server ← → Agents + CLI (parallel)

How it works: * Backend for interactive workflows * CLI for automated workflows * Both access same databases * Workflow history in backend only

Use cases: * Interactive + automated workflows * Team collaboration + CI/CD * Manual testing + automated deployment

Agent Mode Details

Single Agent

Simplest agent setup:

Docker Compose:

services:
  backend:
    ...
  agent:
    image: synthesizedio/tdk-agent
    environment:
      BACKEND_URL: http://backend:8080

Behavior: * One agent processes all tables sequentially * Good for small/medium workloads * Simple configuration

Multiple Agents

Scale horizontally:

Docker Compose:

services:
  backend:
    ...
  agent:
    image: synthesizedio/tdk-agent
    deploy:
      replicas: 3  # 3 agent instances
    environment:
      BACKEND_URL: http://backend:8080

Behavior: * Backend distributes work across agents * Independent tables processed in parallel * Faster overall execution

Example:

Agent 1: customer table
Agent 2: products table
Agent 3: categories table
(all running simultaneously)

See: TDK Agents

Agent Communication

Agents communicate with backend via:

  • Registration: Agent announces availability

  • Heartbeat: Periodic health checks

  • Task assignment: Backend assigns tables to agents

  • Progress updates: Agents report processing status

  • Completion: Final results reported

CLI Mode Details

Running CLI

Direct execution:

tdk \
  --config-file workflow.yaml \
  --inventory-file inventory.yaml

Docker:

docker run synthesizedio/synthesized-tdk-cli \
  -v $(pwd)/config:/config \
  --config-file /config/workflow.yaml \
  --inventory-file /config/inventory.yaml

Kubernetes Job:

apiVersion: batch/v1
kind: Job
metadata:
  name: tdk-masking-job
spec:
  template:
    spec:
      containers:
      - name: tdk
        image: synthesizedio/synthesized-tdk-cli
        args:
          - --config-file
          - /config/workflow.yaml

See: CLI with Kubernetes

CLI vs Agent Mode

Aspect CLI Mode Agent Mode

Configuration

YAML files

UI or API + YAML

Execution

Single process

Distributed

Scaling

Vertical only

Horizontal + Vertical

History

Logs only

Metadata DB

UI

None

Web UI

Scheduling

External (cron, etc.)

Built-in

Choosing a Mode

Use Server + Agent Mode if:

  • Multiple users need access

  • Web UI required

  • Workflow history/auditing needed

  • Scheduled workflows

  • Need horizontal scaling

Use CLI Mode if:

  • Single-purpose automation

  • CI/CD integration

  • No UI needed

  • Simple workflows

  • Minimal infrastructure

Use Hybrid Mode if:

  • Team collaboration (server)

  • Plus automated deployment (CLI)

  • Interactive + scripted workflows

Configuration Differences

Server Mode Config

Workflows stored in backend database, managed via UI/API.

CLI Mode Config

Workflows in YAML files:

workflow.yaml:

default_config:
  mode: MASKING

table_schema:
  - table_name_pattern: "public.*"
  ...

inventory.yaml:

data_sources:
  input:
    url: jdbc:postgresql://...
  output:
    url: jdbc:postgresql://...

What’s Next