# synapseorch-ai/synapse-ai architecture

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

- Interactive diagram: https://gitdiagram.com/synapseorch-ai/synapse-ai
- Repository: https://github.com/synapseorch-ai/synapse-ai

## Overview

1. **Repository shape**
   - This is a monorepo for a multi-agent orchestration platform.
   - It is split into a Python backend, a Next.js frontend, a Python CLI/package entrypoint, and deployment assets for Docker and Kubernetes.

2. **Primary runtime boundary**
   - The **frontend** in `frontend/` is the operator UI: chat, orchestration builder, settings, logs, schedules, messaging, vault, and scale views.
   - The **backend** in `backend/` is the execution and persistence layer: agents, orchestrations, tools, auth, caching, scheduling, messaging, and distributed worker coordination.
   - The frontend’s `src/app/api/*` routes suggest a thin BFF/proxy layer that forwards UI actions to the backend API rather than hosting core business logic itself.

3. **Backend HTTP/API surface**
   - `backend/core/routes/` contains the major API domains: `agents`, `chat`, `orchestrations`, `schedules`, `messaging`, `tools`, `vault`, `settings`, `logs`, `usage`, `auth`, `api_keys`, `builder`, `repos`, `scale`, and more.
   - `backend/core/server.py` and `backend/main.py` appear to wire the HTTP server, route registration, middleware, and runtime startup.
   - `backend/core/api_key_middleware.py`, `internal_auth.py`, and `user_auth.py` define the auth boundary for both local UI usage and programmatic API access.

4. **Agent execution model**
   - The core agent runtime lives in `backend/core/react_engine.py`, `models.py`, `llm_providers.py`, `tools.py`, `tools_registry.py`, and `builder_tools.py`.
   - Agents are described as ReAct-style loops with their own model, prompt, and tools, and can call external capabilities through a registry rather than direct imports.
   - `spawn_subtask.py` indicates the platform can delegate work to temporary sub-agents during execution.

5. **Orchestration subsystem**
   - `backend/core/orchestration/` is the deterministic workflow engine: state, steps, context, logging, summarization, and execution.
   - `backend/core/models_orchestration.py` and `backend/core/native_builder/orchestration.json` show that orchestration definitions are first-class, likely persisted as structured DAGs.
   - The orchestration layer is separate from the agent loop: agents are building blocks, while orchestrations control routing, branching, looping, pauses, and resumptions.

6. **AI builder / meta-agent path**
   - `backend/core/native_builder/` contains prebuilt agent specs such as `agent_creator`, `orchestrator_builder`, `requirements_analyst`, and saver flows.
   - This is the “builder” subsystem that turns natural language into orchestration definitions and agent configurations.
   - The frontend builder UI in `components/orchestration/` maps to this backend flow and lets users visually edit workflows that the backend then executes.

7. **Tooling and external integrations**
   - Native tools live under `backend/tools/` and include filesystem/code utilities, web scraping, PDF/XLSX parsing, SQL, time, and sandboxed bash execution.
   - `backend/core/mcp_client.py` and related files indicate MCP support for connecting to external tool servers.
   - Tooling is intentionally abstracted: agents invoke tools through the registry and runtime, not by embedding integration logic directly.

8. **Messaging and human-in-the-loop**
   - `backend/core/messaging/` is a dedicated integration layer for Discord, Slack, Teams, Telegram, and WhatsApp.
   - These adapters enable workflows to pause for human input or publish results into messaging channels.
   - The messaging store and manager indicate this is not just notifications; it is also part of the workflow interaction surface.

9. **Scheduling and automation**
   - `backend/core/scheduler.py`, `schedule_logger.py`, and `backend/core/models_schedule.py` implement cron/interval automation.
   - The `routes/schedules.py` endpoint family exposes scheduled runs, triggering, and lifecycle management.
   - Schedules can feed orchestrations and then fan out into messaging or other side effects.

10. **State, persistence, and artifacts**
   - Persistent state is split across several concerns: sessions, memory, vault, JSON store, caches, and usage tracking.
   - `backend/core/vault.py` and `s3_storage.py` are the shared artifact/file storage boundary.
   - `backend/core/cache/` covers prompt, response, and tool caching, while `session.py`, `memory.py`, and `json_store.py` manage conversational and operational state.

11. **Scale mode / distributed execution**
   - `backend/core/scale/` is the distributed execution layer described in the README.
   - It includes Redis/pub-sub/event bridge pieces, worker coordination, heartbeat, telemetry, quotas, Postgres state, and webhook handling.
   - The repo distinguishes between a stateless API server and separate worker processes (`backend/worker_main.py`, `backend/core/scale/worker.py`), which is the key boundary for diagramming scale mode.

12. **Infrastructure and deployment**
   - Dockerfiles exist for the full app, backend, frontend, and worker, confirming independently deployable runtime images.
   - `docker-compose.yml` models the full local stack, while `infra/k8s/` contains production manifests including API, worker, PgBouncer, and autoscaling objects.
   - The deployment story is tied to the scale architecture: API, workers, Redis, Postgres, and S3 are separate operational concerns.

13. **Frontend composition**
   - The frontend uses Next.js app routing with a structured admin console.
   - `components/settings/` covers operational management pages; `components/orchestration/` covers workflow design; `StoreProvider.tsx` and `store/` indicate central UI state management.
   - `frontend/src/lib/backend.ts` suggests the UI talks to the backend through a shared client wrapper.

14. **Packaging and user entrypoints**
   - `synapse/`, `bin/`, `setup.sh`, `setup.ps1`, and `docs/cli.md` indicate a distributable CLI that starts, stops, upgrades, and bootstraps the app.
   - This is a productized platform, not just a library: installation can happen via pip, npm, Docker, or the provided installer scripts.

15. **Useful diagram takeaway**
   - A good architecture diagram should show: UI and API proxy on one side; backend HTTP/API, orchestration engine, agent runtime, tool registry, auth, and persistence in the center; and distributed scale services plus workers, Redis, Postgres, S3, and messaging/LLM/external tool integrations on the edges.

Main entry points: [`backend/core/routes`](https://github.com/synapseorch-ai/synapse-ai/tree/master/backend/core/routes) (API Domains), [`backend/core/react_engine.py`](https://github.com/synapseorch-ai/synapse-ai/blob/master/backend/core/react_engine.py) (Agent Runtime), [`backend/core/orchestration`](https://github.com/synapseorch-ai/synapse-ai/tree/master/backend/core/orchestration) (Orchestration Engine), [`backend/core/server.py`](https://github.com/synapseorch-ai/synapse-ai/blob/master/backend/core/server.py) (HTTP Server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_ui_console["Operator UI<br/>Next.js app"]
  node_ui_bff["API Proxy<br/>Next.js routes"]
  node_ui_builder["Workflow Builder<br/>React builder"]
  node_ui_settings["Settings Panels<br/>React admin"]
end

subgraph group_backend_api["Backend API"]
  node_api_server["HTTP Server<br/>FastAPI wiring<br/>[server.py]"]
  node_api_routes["API Domains<br/>route modules"]
  node_auth_boundary["Auth Boundary<br/>auth middleware"]
end

subgraph group_runtime["Core Runtime"]
  node_agent_runtime["Agent Runtime<br/>ReAct engine<br/>[react_engine.py]"]
  node_agent_models["Agent Models<br/>schemas<br/>[models.py]"]
  node_tool_registry["Tool Registry<br/>tool abstraction<br/>[tools_registry.py]"]
  node_native_tools["Native Tools<br/>tooling"]
  node_orchestration_engine["Orchestration Engine<br/>workflow engine"]
  node_builder_flow["Builder Flow<br/>meta-agent"]
  node_persistence[("State & Storage<br/>persistence layer<br/>[session.py]")]
  node_messaging["Messaging Hub<br/>integrations"]
  node_scheduler["Scheduler<br/>automation<br/>[scheduler.py]"]
end

subgraph group_scale["Scale Mode"]
  node_scale_runtime["Scale Control<br/>distributed runtime"]
  node_worker_entry["Worker Process<br/>worker entrypoint<br/>[worker_main.py]"]
end

subgraph group_deploy["Deployment"]
  node_deployment_stack["Deployment Stack<br/>Docker/K8s<br/>[docker-compose.yml]"]
  node_cli_entry["CLI Installer<br/>package entrypoint<br/>[cli.py]"]
end

node_ui_console -->|"uses"| node_ui_bff
node_ui_builder -->|"embedded in"| node_ui_console
node_ui_settings -->|"embedded in"| node_ui_console
node_ui_bff -->|"calls"| node_api_server
node_api_server -->|"guards"| node_auth_boundary
node_api_server -->|"mounts"| node_api_routes
node_api_routes -->|"drives"| node_agent_runtime
node_api_routes -->|"controls"| node_orchestration_engine
node_api_routes -->|"manages"| node_scheduler
node_api_routes -->|"exposes"| node_messaging
node_api_routes -->|"reads/writes"| node_persistence
node_agent_runtime -->|"invokes"| node_tool_registry
node_tool_registry -->|"dispatches"| node_native_tools
node_agent_runtime -->|"stores state"| node_persistence
node_orchestration_engine -->|"orchestrates"| node_agent_runtime
node_builder_flow -->|"emits"| node_orchestration_engine
node_builder_flow -->|"creates"| node_agent_runtime
node_scheduler -->|"triggers"| node_orchestration_engine
node_messaging -->|"pauses/resumes"| node_orchestration_engine
node_scale_runtime -->|"runs in"| node_worker_entry
node_scale_runtime -->|"syncs with"| node_api_server
node_worker_entry -->|"executes"| node_orchestration_engine
node_worker_entry -->|"hosts"| node_agent_runtime
node_deployment_stack -->|"deploys"| node_api_server
node_deployment_stack -->|"deploys"| node_worker_entry
node_cli_entry -->|"boots"| node_deployment_stack
node_cli_entry -.->|"opens"| node_ui_console

click node_ui_console "https://github.com/synapseorch-ai/synapse-ai/tree/master/frontend/src/app"
click node_ui_bff "https://github.com/synapseorch-ai/synapse-ai/tree/master/frontend/src/app/api"
click node_ui_builder "https://github.com/synapseorch-ai/synapse-ai/tree/master/frontend/src/components/orchestration"
click node_ui_settings "https://github.com/synapseorch-ai/synapse-ai/tree/master/frontend/src/components/settings"
click node_api_server "https://github.com/synapseorch-ai/synapse-ai/blob/master/backend/core/server.py"
click node_api_routes "https://github.com/synapseorch-ai/synapse-ai/tree/master/backend/core/routes"
click node_auth_boundary "https://github.com/synapseorch-ai/synapse-ai/blob/master/backend/core/api_key_middleware.py"
click node_agent_runtime "https://github.com/synapseorch-ai/synapse-ai/blob/master/backend/core/react_engine.py"
click node_agent_models "https://github.com/synapseorch-ai/synapse-ai/blob/master/backend/core/models.py"
click node_tool_registry "https://github.com/synapseorch-ai/synapse-ai/blob/master/backend/core/tools_registry.py"
click node_native_tools "https://github.com/synapseorch-ai/synapse-ai/tree/master/backend/tools"
click node_orchestration_engine "https://github.com/synapseorch-ai/synapse-ai/tree/master/backend/core/orchestration"
click node_builder_flow "https://github.com/synapseorch-ai/synapse-ai/tree/master/backend/core/native_builder"
click node_persistence "https://github.com/synapseorch-ai/synapse-ai/blob/master/backend/core/session.py"
click node_messaging "https://github.com/synapseorch-ai/synapse-ai/tree/master/backend/core/messaging"
click node_scheduler "https://github.com/synapseorch-ai/synapse-ai/blob/master/backend/core/scheduler.py"
click node_scale_runtime "https://github.com/synapseorch-ai/synapse-ai/tree/master/backend/core/scale"
click node_worker_entry "https://github.com/synapseorch-ai/synapse-ai/blob/master/backend/worker_main.py"
click node_deployment_stack "https://github.com/synapseorch-ai/synapse-ai/blob/master/docker-compose.yml"
click node_cli_entry "https://github.com/synapseorch-ai/synapse-ai/blob/master/synapse/cli.py"

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_ui_console,node_ui_bff,node_ui_builder,node_ui_settings toneBlue
class node_api_server,node_api_routes,node_auth_boundary toneAmber
class node_agent_runtime,node_agent_models,node_tool_registry,node_native_tools,node_orchestration_engine,node_builder_flow,node_persistence,node_messaging,node_scheduler toneMint
class node_scale_runtime,node_worker_entry toneRose
class node_deployment_stack,node_cli_entry toneIndigo
```

## Components

### Frontend

Next.js operator console and BFF routes

- [Operator UI](https://github.com/synapseorch-ai/synapse-ai/tree/master/frontend/src/app): Next.js app · Chat, builder, settings, logs, schedules, messaging, vault, and scale views · `frontend/src/app`
- [API Proxy](https://github.com/synapseorch-ai/synapse-ai/tree/master/frontend/src/app/api): Next.js routes · Thin UI-facing routes that forward actions to the backend · `frontend/src/app/api`
- [Workflow Builder](https://github.com/synapseorch-ai/synapse-ai/tree/master/frontend/src/components/orchestration): React builder · Visual orchestration editor and workflow canvas · `frontend/src/components/orchestration`
- [Settings Panels](https://github.com/synapseorch-ai/synapse-ai/tree/master/frontend/src/components/settings): React admin · Operational tabs for agents, tools, models, messaging, vault, schedules, and scale · `frontend/src/components/settings`

### Backend API

HTTP surface and auth boundary

- [HTTP Server](https://github.com/synapseorch-ai/synapse-ai/blob/master/backend/core/server.py): FastAPI wiring · Server startup, middleware, and route registration · `backend/core/server.py`
- [API Domains](https://github.com/synapseorch-ai/synapse-ai/tree/master/backend/core/routes): route modules · Major endpoints for agents, chat, orchestrations, schedules, tools, messaging, vault, logs, usage, auth, and scale · `backend/core/routes`
- [Auth Boundary](https://github.com/synapseorch-ai/synapse-ai/blob/master/backend/core/api_key_middleware.py): auth middleware · API key, internal auth, and user auth enforcement · `backend/core/api_key_middleware.py`

### Core Runtime

Agents, orchestration, tools, state, and persistence

- [Agent Runtime](https://github.com/synapseorch-ai/synapse-ai/blob/master/backend/core/react_engine.py): ReAct engine · LLM-driven agent loop with prompts, tools, models, and subtask spawning · `backend/core/react_engine.py`
- [Agent Models](https://github.com/synapseorch-ai/synapse-ai/blob/master/backend/core/models.py): schemas · Agent, tool, session, and runtime data models · `backend/core/models.py`
- [Tool Registry](https://github.com/synapseorch-ai/synapse-ai/blob/master/backend/core/tools_registry.py): tool abstraction · Tool dispatch layer that exposes native and external capabilities · `backend/core/tools_registry.py`
- [Native Tools](https://github.com/synapseorch-ai/synapse-ai/tree/master/backend/tools): tooling · Filesystem, web, PDF/XLSX, SQL, bash, and data collection tools · `backend/tools`
- [Orchestration Engine](https://github.com/synapseorch-ai/synapse-ai/tree/master/backend/core/orchestration): workflow engine · Deterministic orchestration state, steps, context, logging, and summarization · `backend/core/orchestration`
- [Builder Flow](https://github.com/synapseorch-ai/synapse-ai/tree/master/backend/core/native_builder): meta-agent · Native builder agents and orchestration spec generation · `backend/core/native_builder`
- [State & Storage](https://github.com/synapseorch-ai/synapse-ai/blob/master/backend/core/session.py): persistence layer · Sessions, memory, cache, vault, JSON store, and artifact storage · `backend/core/session.py`
- [Messaging Hub](https://github.com/synapseorch-ai/synapse-ai/tree/master/backend/core/messaging): integrations · Discord, Slack, Teams, Telegram, and WhatsApp adapters plus store and manager · `backend/core/messaging`
- [Scheduler](https://github.com/synapseorch-ai/synapse-ai/blob/master/backend/core/scheduler.py): automation · Cron and interval scheduling with lifecycle and run logging · `backend/core/scheduler.py`

### Scale Mode

Distributed workers and coordination

- [Scale Control](https://github.com/synapseorch-ai/synapse-ai/tree/master/backend/core/scale): distributed runtime · Redis/pub-sub, worker heartbeat, telemetry, quotas, webhook sync, and worker coordination · `backend/core/scale`
- [Worker Process](https://github.com/synapseorch-ai/synapse-ai/blob/master/backend/worker_main.py): worker entrypoint · Separate worker runtime and worker main entrypoint · `backend/worker_main.py`

### Deployment

Packaging, containers, and Kubernetes

- [Deployment Stack](https://github.com/synapseorch-ai/synapse-ai/blob/master/docker-compose.yml): Docker/K8s · Dockerfiles, compose stack, and Kubernetes manifests for API, worker, and PgBouncer · `docker-compose.yml`
- [CLI Installer](https://github.com/synapseorch-ai/synapse-ai/blob/master/synapse/cli.py): package entrypoint · Synapse CLI and setup scripts for bootstrap, start, stop, and upgrade flows · `synapse/cli.py`

## Connections

- Operator UI → API Proxy: uses · User actions flow through browser routes
- Workflow Builder → Operator UI: embedded in · Builder UI is part of the operator console
- Settings Panels → Operator UI: embedded in · Settings panels are part of the operator console
- API Proxy → HTTP Server: calls · Frontend routes forward to backend services
- HTTP Server → Auth Boundary: guards · All API access is filtered through auth middleware
- HTTP Server → API Domains: mounts · Server wires domain route modules
- API Domains → Agent Runtime: drives · Chat, agents, and builder endpoints trigger execution
- API Domains → Orchestration Engine: controls · Workflow endpoints create, run, resume, and inspect orchestrations
- API Domains → Scheduler: manages · Schedule endpoints configure and trigger automation
- API Domains → Messaging Hub: exposes · Messaging endpoints configure channel integrations
- API Domains → State & Storage: reads/writes · Most routes persist sessions, settings, logs, vault items, and usage
- Agent Runtime → Tool Registry: invokes · Agents call tools through the registry abstraction
- Tool Registry → Native Tools: dispatches · Registry resolves native and sandboxed tools
- Agent Runtime → State & Storage: stores state · Agent execution relies on sessions, memory, cache, and artifacts
- Orchestration Engine → Agent Runtime: orchestrates · Workflows compose agent steps and control branching or pauses
- Builder Flow → Orchestration Engine: emits · Meta-agents generate orchestration definitions and agent specs
- Builder Flow → Agent Runtime: creates · Builder agents draft or update agents and workflows
- Scheduler → Orchestration Engine: triggers · Scheduled jobs launch orchestrations
- Messaging Hub → Orchestration Engine: pauses/resumes · Human-in-the-loop messages can unblock runs
- Scale Control → Worker Process: runs in · Distributed control plane coordinates worker processes
- Scale Control → HTTP Server: syncs with · API server publishes events and state to scale services
- Worker Process → Orchestration Engine: executes · Workers execute workflow steps and agent tasks
- Worker Process → Agent Runtime: hosts · Worker processes run agent execution loops
- Deployment Stack → HTTP Server: deploys · Container and cluster assets package the API service
- Deployment Stack → Worker Process: deploys · Separate images and manifests package worker processes
- CLI Installer → Deployment Stack: boots · CLI and installers start and manage the stack
- CLI Installer → Operator UI: opens · Local setup can launch the operator UI