Architecture¶

Documentation home · Previous: CLI · Next: Deployment

Synapse is clean-architecture Go. Dependencies point inward only.

External CI/CD connections use the same rule: provider-neutral domain/use-case contracts depend on a code-owned registry, while Jenkins lives in infrastructure. See External CI/CD integrations.

domain  <-  usecase  <-  adapter / infrastructure

The dependency rule¶

Layer	Path	May import
domain	`internal/domain/*`	only domain and the standard library; `golang.org/x/net/idna` is the sole sanctioned pure-Go standards exception for canonical IDNA processing
usecase	`internal/usecase/*`	domain and the ports it defines
adapter	`internal/adapter/*`	usecase and domain
infrastructure	`internal/infrastructure/*`	the ports it implements, plus domain
platform	`internal/platform/*`	standard library, domain and ports
composition	`internal/composition/*`	usecase, infrastructure, and platform packages needed for shared composition

All external I/O (database, tools, LLM, sandbox, storage) goes through ports, which are interfaces in internal/usecase/ports. The domain stays pure, with no framework, database, or tool types in it. cmd/* remains the composition root: it wires concrete implementations into the interfaces in main, and holds no business logic. Shared wiring that is reused by multiple binaries lives in internal/composition/*, above the platform and infrastructure packages it composes.

PR/MR decoration follows the same boundary. ports.PRDecorator carries only a normalized forge target plus the quality-gate result, deterministic Markdown summary, and stored line annotations; credentials stay outside the render payload. Project-analysis completion and the CLI gate finalize path call the port fail-soft, and incomplete PR identity is skipped rather than guessed. Provider-specific network adapters and opt-in wiring are separate follow-up work, so this foundation does not contact a forge by itself.

Projects and engagements¶

A Project is a long-lived code-quality identity: it binds source and configuration and will own its analysis history. An Engagement is a time-bounded security assessment whose scope, authorization window, and lifecycle gate all execution. They are independent aggregates; neither owns the other. Both may invoke the same analysis pipeline, while future project analyses reference their Project instead of duplicating or forking that engine.

An Assessment Cycle owns rooted Assessment/Re-test ancestry and a frozen Asset/Project boundary. Immutable Snapshots own selected sealed run inputs; Comparisons own directional presence results. Closure manifests are built transactionally, sealed once, and thereafter may only be superseded. Their ordered path and typed immutable references remain tenant-scoped under forced PostgreSQL RLS. Lifecycle migrations and historical backfills are separate: API/worker startup never runs backfill commands, and all rollout gates default off.

Binaries¶

cmd/ holds the service, operational, helper, and agent composition roots.

Services

Binary	Role
`synapse-api`	HTTP API server, the primary service and largest composition root.
`synapse-worker`	Durable, lease-based job runner for recon, scheduled provider work, and background jobs. Leader-gated.
`synapse-mcp`	Read and propose-only MCP integration. It has no executor and no gate, so it never executes.

Command line

Binary	Role
`synapse-cli`	CI-oriented scanner and code-quality gate using the same pipeline as the server.

Assessment lifecycle operations

Binary	Role
`synapse-assessment-backfill`	Resumable tenant-scoped historical singleton-Cycle backfill.
`synapse-assessment-snapshot-backfill`	Append-only projection of historical scan evidence into legacy Snapshots with explicit unknown coverage.
`synapse-finding-lineage-backfill`	Resumable conversion of legacy Findings into versioned Identities, immutable Observations, review Candidates, or explicit redacted Skip records.
`synapse-assessment-comparison-backfill`	Tenant-scoped shadow Comparison generation and deterministic failed-item repair.
`synapse-assessment-integrity`	Read-only Cycle integrity verification and deterministic repair-plan output.
`synapse-assessment-rollout-gate`	Offline fail-closed evaluator for canary, read-cutover, UI-default, and rollback evidence.

Historical relationship review remains inside synapse-api: immutable candidates are derived from frozen Cycle, Snapshot, and Finding inputs. Confirmation creates only an append-only blocked repair plan; this slice has no graph-mutation executor.

Sandboxed helpers

Each isolates a capability-sensitive or untrusted-input workload out of the server process.

Binary	Role
`synapse-callgraph`	`go/ssa` call-graph builder for reachability and taint.
`synapse-ast`	tree-sitter AST parsing of untrusted source. Exit code 3 means the backend is unavailable in a CGO-free build.
`synapse-cspm`	Cloud posture collection for AWS, Azure, and GCP. Read-only, with credentials passed by inherited file descriptor.
`synapse-dast-helper`	Governed DAST crawling and checks under kernel-enforced egress confinement.
`synapse-egress-broker`	The root-owned broker that attaches and configures a run's network namespace. It is the only component that runs `ip` and `iptables`, so the worker never holds that privilege. See deployment.
`synapse-sandbox-check`	Conformance check for the sandbox on this host: filesystem confinement, effective capabilities, the memory limit, network isolation, and binary integrity. `-mode startup` on boot, `-mode full` to exercise every control, `-strict` to fail when one is unenforced.

Fleet agents

Binary	Role
`synapse-agent`	Host inventory and, on Linux, eBPF runtime detections.
`synapse-cluster-agent`	Kubernetes workload, exposure, and identity inventory.

AI-triage evaluation tools

Offline governance utilities. None participates in a live scan.

Binary	Role
`synapse-fptriage-eval`	Offline evaluation harness against golden datasets.
`synapse-fptriage-compare`	Deterministic candidate-versus-baseline promotion gate.
`synapse-fptriage-release`	Versioned promotion and rollback ledger.
`synapse-fptriage-curate`	Privacy- and label-reviewed reviewer-feedback curation.
`synapse-fptriage-drift`	Input distribution drift detection.

Tool integration¶

Light, pure-Go tools run in process as libraries. The SBOM producer and the advisory store are among them: both are Synapse's own, so a stock scan shells out to no third-party scanner. Heavy or capability-sensitive tools are shelled out to pinned binaries via argv arrays: the recon tools, and Syft or Grype when an operator opts into either as a cross-check. The same rule isolates heavy analysis of untrusted source. The call-graph builder runs only inside the sandboxed synapse-callgraph binary, never in the server process.

The AI analysis layer¶

The analysis layer is a cross-cutting concern that turns raw scanner and agent output into confirmed findings. It is deterministic-first and gated. Every claim is a typed judgment with a lifecycle of propose, verify, confirm. Gated capabilities promote only on a distinct verifier's sealed verdict above the evidence threshold. The agent is propose-only, so it can never confirm its own claim. No model ever sits in the report path.

Persistence and migrations¶

Persistence is PostgreSQL when a DSN is set, and an in-memory store otherwise. Migrations are numbered SQL files embedded in the binary. Development services apply them automatically; production uses the dedicated synapse-migrate command with the owner credential before API, worker, and MCP start with their runtime credential. A shipped migration is never edited. A new numbered file is appended.

Production rollouts are migrate-first and migrations must be backward-compatible and phased: apply the schema expansion before deploying binaries that use it, and defer destructive changes until every older binary is gone. The API remains live but reports stale schema through /readyz; workers and the MCP server refuse startup on stale schema because they have no readiness endpoint to withdraw. Readiness accepts only an applied database migration newer than the binary's embedded maximum, which permits that migrate-first overlap while rejecting a missing, down, or divergent required migration.

Next: Deployment