Graph Designer Tool

Date: 2026-04-16
Status: Draft

1. Intentions

Designing and communicating systems that have a graph-shaped structure — components and their relationships — is a common but underserved need. Existing general-purpose diagramming tools either lock data into opaque proprietary formats, or lack the semantic depth to carry domain-specific information alongside the visual representation.

This tool exists to close that gap. The core convictions behind it are:

Graphs are data, not just pictures. Every node, edge, and group should be a first-class data entity carrying an open-ended metadata payload. The diagram is a view over that data, not the data itself.

Structure should be discoverable, not manual work. Laying out a graph by hand is tedious and error-prone. The tool should handle placement, spacing, and routing automatically, with enough tuning knobs for the user to guide the result toward their intent.

Hierarchy is intrinsic to most real systems. Components naturally nest — a service contains subservices, a domain owns modules. The data model and the visual representation must both express this nesting natively, not as an afterthought.

Zero infrastructure. The tool should run in a browser against any ordinary HTTP server and persist everything locally. No accounts, no backend, no configuration ceremony.

Composability across abstraction levels. A graph that describes a subsystem should be reusable as a single node inside a higher-level graph. This allows a system to be modelled at multiple levels of detail without duplicating structure — the viewer zooms into a node and sees the full graph it represents.

AI as a first-class authoring partner. Constructing and refining a graph should be possible through natural language as well as direct manipulation. AI assistance operates at the granularity of individual nodes and edges, so the user can describe intent and have the model apply precise, targeted changes — without losing control of the underlying data.

2. High-Level Requirements

2.1 Graph Model

• A graph is a named, independently addressable document consisting of nodes, edges, and groups.
• Multiple graphs can coexist and be managed within a single tool instance.
• A graph document is fully self-contained: all nodes, edges, groups, layout configuration, and optional schema live inside it.
• The graph can be exported to and imported from a canonical JSON format without loss of information.
• Graphs are composable: any graph can be embedded as a node inside another graph, forming a multi-level hierarchy of graphs. The embedding node acts as a proxy for the referenced graph, and the reference is navigable (drill down / back up).

2.2 Nodes and Edges

• A node is an entity with an identity, a label, an optional type token, and a flexible metadata payload — an arbitrary JSON object with no fixed schema.
• A node may optionally carry a graph reference (graphRef) — a pointer to another graph document stored in the same tool instance. A node with a graphRef is a composite node: it represents the entirety of the referenced graph at the current level of abstraction.
• An edge is a relationship between two nodes (or groups), carrying a directionality flag, an optional label, and the same flexible metadata payload as nodes.
• Node types are user-defined and carry no built-in semantics; they exist to allow consumers of the exported data to apply their own meaning.
• An optional JSON Schema can be attached at the graph or type level to validate metadata shape. Validation is advisory and never blocks authoring.

2.3 Grouping and Hierarchy

• Any set of nodes and groups can be collected into a named group, forming a containment hierarchy of arbitrary depth.
• Groups are first-class entities in the data model: they have their own identity, label, and metadata payload.
• A group can be in an expanded state (showing its contents) or a collapsed state (presenting as a single opaque element with its incident edges still visible).
• The hierarchy is acyclic; a group cannot directly or transitively contain itself.
• Edges may connect any combination of nodes and groups regardless of nesting depth.

2.4 Automatic Layout

• The tool must be capable of computing a collision-free, readable spatial arrangement for any graph automatically, without requiring the user to manually position elements.
• At least four layout strategies must be available: hierarchical (rank-based), force-directed (physics simulation), radial (hub-and-spoke), and grid (uniform matrix).
• Each strategy exposes a concise set of tunable parameters so the user can steer the output (e.g., flow direction, spacing, density) without implementing the algorithm themselves.
• Layout can be applied to the full graph or scoped to a subgraph or group.
• Node sizes are derived automatically from content; explicit overrides are respected.
• Manual positional adjustments made after a layout run are stable until the next explicit layout is requested.

2.5 Persistence

• All graph data is stored locally in the browser (IndexedDB as the primary store, localStorage as a fallback) with no dependency on a remote server.
• Persistence is automatic and continuous; no explicit save action should be required to avoid data loss.
• The tool restores its last state on next load, including which graph was active and the last viewport position.

2.6 Delivery Constraints

• The tool is delivered as a static bundle (HTML, JS, CSS, assets) that requires no server-side runtime.
• Any standard HTTP file server is sufficient to host it.
• The bundle has no external runtime dependencies; it must work in an air-gapped environment.

2.7 AI-Assisted Graph Editing

AI can help edit the content of individual nodes and edges — labels, types, and metadata — through natural language. Graph structure (what exists and how things connect) remains entirely under human control; LLMs are not well-suited to making structural decisions on the user's behalf.

3. Out of Scope (v1)

• Real-time collaboration.
• Server-side or cloud persistence.
• Version history and branching.
• Code generation from graph structure.
• Plugin or extension system.
• Mobile / touch-first experience.
• AI-driven automatic full-graph generation from scratch (AI editing operates on existing elements only).
• AI layout or routing decisions (layout remains a deterministic algorithm; AI operates on data, not on spatial placement).
• Embedded / local AI model inference; an external API provider is required.