Architecture

Synth uses a two-tier architecture: a central Synth server and distributed Envoy agents.

Synth Server

The brain of Synth. The server is a Fastify-based Node.js application that manages all deployment state, runs the intelligent agent, and exposes both a REST API and an MCP server.

• REST API — CRUD for partitions, artifacts, environments, and deployments
• MCP Server — Model Context Protocol server for tool-based AI integration
• Agent — Intent resolution, pipeline planning, and deployment orchestration
• Debrief — Decision log with SQLite persistence
• Entity Store — SQLite-backed storage for all entities

Envoy

Lightweight agents deployed on target machines. Envoys receive deployment instructions from the Synth server, execute steps locally, run health checks, and report results back.

• Deployment executor — Runs shell commands with variable injection and timeouts
• Health reporting — Periodic status reports to Synth
• Query engine — Local environment inspection for diagnostics

Data Flow

Engineer → Synth (resolve intent, plan pipeline, create deployment)
Synth → Envoy (dispatch deployment steps)
Envoy → Target Machine (execute commands, health checks)
Envoy → Synth (report results)
Synth → Debrief (log every decision)

Partition Isolation

Every partition is a logically isolated context. Queries are always scoped to a single partition. The agent never sees data from other partitions, and failures in one partition cannot propagate to another.

MCP Integration

Synth exposes deployment operations as MCP tools, making them accessible to any MCP-compatible AI client. It also connects to external MCP servers for data enrichment — monitoring, CI/CD, and infrastructure data can flow into the agent's decision-making.