Problem
Most diagramming tools treat a system architecture as a picture. System Synthesis treats it as a shared, versioned graph with enforceable permissions, deterministic analysis, durable history, and an explicit path to infrastructure exports. The hard part was not drawing nodes; it was preserving useful behaviour under concurrency, reconnection, authorization changes, and partial infrastructure support.
Constraints
- Multiple clients can edit independent fields on the same graph entity at the same time.
- Unauthorized viewers, cross-board mutations, malformed payloads, and oversized updates must be rejected.
- An accepted collaboration update must be durable before it is broadcast.
- Duplicate and reordered delivery must not cause clients to diverge.
- Architecture findings and exports must be reproducible without depending on an LLM response.
- Restart recovery and cross-instance transport must rebuild the same canonical document state.
Architecture
- 1
React Flow canvas
Projects graph interactions into a client-side store without becoming the source of truth.
- 2
Granular Yjs document
Stores nodes and edges as nested maps so independent fields can merge separately.
- 3
Authorized Socket.IO boundary
Verifies JWT identity, board role, joined room, payload size, and event schema for every mutation.
- 4
PostgreSQL update log
Appends hash-deduplicated updates under a per-board advisory lock before room application.
- 5
Redis transport
Distributes accepted updates between active server instances and triggers durable replay after recovery.
- 6
Deterministic engines
Run graph rules, semantic history, and validated Terraform or Compose generation over canonical state.
Design decisions
Yjs instead of broadcasting whole JSON objects
Whole-object replacement makes an unrelated rename and movement overwrite one another. Nested Y.Maps reduce the conflict unit to individual fields while preserving deterministic resolution when two users change the same scalar value.
PostgreSQL for authority, Redis for transport
Redis is useful for low-latency cross-instance delivery but is not the durable record. Accepted updates enter PostgreSQL before application and broadcast; Redis then distributes them to active rooms.
Deterministic findings before optional AI explanation
Reachability, cycles, articulation points, bridges, dependency depth, blast radius, and trust-boundary checks produce the authoritative finding set. An LLM may explain those findings but cannot create or remove them.
Validated intermediate representation for exports
Terraform and Compose generation share a schema-validated IR, stable naming, ordering, pinned versions, provenance hashes, and explicit unsupported-resource errors instead of best-effort output.
Correctness and testing
- A seeded convergence harness injects duplicates, delays, reordering, local undo, two logical server documents, and simulated restart recovery.
- Canonical document hashes are compared after 10 simulated clients execute 1,000 randomized operations.
- Authenticated REST and WebSocket integration checks cover viewers, cross-board access, malformed input, and oversized mutations.
- The backend suite contains 64 tests spanning security, durability, granular merge behaviour, graph algorithms, exports, history, and AI provenance.
- Golden files verify stable Terraform and Docker Compose generation.
Failure cases
- If durable persistence cannot be established, the mutation is rejected rather than broadcast optimistically.
- A disconnected editor pauses instead of pretending the application is offline-first.
- Concurrent edits to the same scalar field converge deterministically but do not preserve both users' intent.
- Unsupported infrastructure resources produce explicit export errors.
Results
- 10 simulated clients converged after 1,000 randomized operations with duplicated and reordered delivery.
- Independent fields on the same node merge without whole-object overwrites in the tested model.
- Supported infrastructure exports are stable across repeated runs.
- Authorization and durability failures reject mutations instead of silently degrading consistency.
Limitations
The system is intentionally described within the boundaries supported by its implementation and evidence.
- The system is not a formal proof that an architecture is correct.
- It is not a complete replacement for Terraform, Docker Compose, or Kubernetes.
- The in-memory development mode is not restart-durable or horizontally scalable.
- The public frontend demo does not represent measured production capacity for the collaboration backend.
- LLM output is explanatory only and is never authoritative validation.