synapseorch-ai/synapse-ai

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.