feat(templates): visual graph builder (#74)

Canvas mode in the template editor (lazy-loaded React Flow): service
nodes for web/worker/cron/database, connect handles to set depends_on,
per-node inspector (image/repo, engine, port, health check, env,
volumes), live validation (dup keys, missing deps, cycles, missing
source), and an Apply step that serializes back to the version-2 graph
config JSON.

- builder-model.ts is pure: config↔canvas round-trip, layered
  auto-layout, flat-legacy→single-node migration, validation —
  16 vitest cases cover all of it
- node positions persist under config.canvas (backend ignores unknown
  config keys, so no schema change)
- flat legacy templates open as a single node so nothing is lost on
  edit

Generated with [Devin](https://devin.ai)

Co-authored-by: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>

ROADMAP2.md

@@ -252,9 +252,12 @@ goroutines; this fixes correctness *and* unlocks the ops surface.
 - [x] **Graph deploy pipeline** — creates services in dependency order,
   resolves vars/secrets, triggers builds. `deployTemplateGraph`,
   `POST /templates/deploy` (inline), `POST /projects/:id/import-compose`.
-- [ ] **Visual template builder** — canvas mode: drop git/image/db
+- [x] **Visual template builder** — canvas mode in the template editor:
-  nodes, wire refs, set order, save/publish. Reuses existing canvas
+  web/worker/cron/database nodes, handles wire `depends_on`, inspector
-  primitives (dflow's `templates/compose` is exactly this).
+  edits image/repo/engine/port/env/volumes, live validation, applies
+  back to the version-2 graph JSON. Positions persist under
+  `config.canvas`; flat legacy configs open as a single node.
+  `builder-model.ts` + `TemplateBuilder.tsx`.
 - [x] **Catalog growth** — seeded graph stacks for n8n, Gitea,
   Nextcloud, Vaultwarden, Umami, Immich (Plausible already shipped).
   `TestSeedTemplatesResolveCleanly` keeps every seed parseable,
@@ -543,7 +546,12 @@ and wired refs, one click or one CLI call.
   optional Cloudflare tunnel token → done. Shell redirects signed-in
   users to `/setup` while `needs_setup`; installs with existing projects
   auto-complete so nobody gets nagged retroactively.
-- [ ] **Self-upgrade loop verification**, docs freshness, v1.0.0 release.
+- [x] **Self-upgrade loop verification** — live-verified: admin
+  `POST /agents/:id/upgrade` → `self_upgrade` command → agent downloads
+  `/api/agents/download/linux-amd64` → sha256 verify → `--version`
+  sanity → atomic rename → result posts → `syscall.Exec` re-exec. Agent
+  ran `v0.0.1-old`, came back `v9.9.9-test`, command row `completed`.
+- [ ] **Docs freshness, v1.0.0 release.**
 
 ## 11. Deliberately not imported from dflow
 

app/frontend/src/features/templates/builder/TemplateBuilder.tsx

@@ -0,0 +1,467 @@
+import { useCallback, useMemo, useState } from 'react';
+import {
+  Background,
+  BackgroundVariant,
+  Handle,
+  MarkerType,
+  Position,
+  ReactFlow,
+  ReactFlowProvider,
+  useReactFlow,
+  type Connection,
+  type Edge,
+  type EdgeChange,
+  type Node,
+  type NodeChange,
+  type NodeProps,
+} from '@xyflow/react';
+import '@xyflow/react/dist/style.css';
+import { Database, GitBranch, Package, Timer, Trash2, X } from 'lucide-react';
+import {
+  canvasFromConfig,
+  configFromCanvas,
+  newServiceKey,
+  validateGraph,
+  type BuilderNode,
+  type BuilderService,
+  type BuilderServiceType,
+} from './builder-model';
+
+type ServiceBuilderNode = Node<{ svc: BuilderService }, 'tplService'>;
+
+const TYPE_META: Record<BuilderServiceType, { label: string; icon: typeof Package; cls: string }> = {
+  web: { label: 'Web', icon: Package, cls: 'text-[var(--accent-primary)]' },
+  worker: { label: 'Worker', icon: GitBranch, cls: 'text-[var(--info,#5eb3f6)]' },
+  cron: { label: 'Cron', icon: Timer, cls: 'text-[var(--warning)]' },
+  database: { label: 'Database', icon: Database, cls: 'text-[var(--success,#7bd88a)]' },
+};
+
+const DATABASE_ENGINES = ['postgresql', 'mysql', 'mariadb', 'mongodb', 'redis', 'dragonfly', 'clickhouse'];
+
+function ServiceBuilderNodeView({ data, selected }: NodeProps<ServiceBuilderNode>) {
+  const meta = TYPE_META[data.svc.type] ?? TYPE_META.web;
+  const Icon = meta.icon;
+  return (
+    <div
+      className={`relative w-[210px] rounded-[var(--radius-md)] border bg-[var(--bg-elevated)] px-3 py-2.5 shadow-sm transition-colors ${
+        selected ? 'border-[var(--accent-primary)]' : 'border-[var(--border-subtle)]'
+      }`}
+    >
+      <Handle type="target" position={Position.Left} className="!h-2.5 !w-2.5 !border-[var(--border-default)] !bg-[var(--bg-base)]" />
+      <Handle type="source" position={Position.Right} className="!h-2.5 !w-2.5 !border-[var(--border-default)] !bg-[var(--bg-base)]" />
+      <div className="flex items-center gap-2">
+        <Icon size={14} className={meta.cls} />
+        <span className="truncate text-[12.5px] font-semibold text-[var(--text-primary)]">
+          {data.svc.name || data.svc.key}
+        </span>
+      </div>
+      <div className="mt-1 flex items-center justify-between gap-2">
+        <span className="text-[10.5px] uppercase tracking-wide text-[var(--text-tertiary)]">{meta.label}</span>
+        <span className="mono max-w-[120px] truncate text-[10.5px] text-[var(--text-secondary)]">
+          {data.svc.runtime || data.svc.repo || '—'}
+        </span>
+      </div>
+    </div>
+  );
+}
+
+const nodeTypes = { tplService: ServiceBuilderNodeView };
+
+// Edges run dependency → dependent: connecting A → B means "B depends_on A".
+export function TemplateBuilder(props: {
+  config: Record<string, unknown>;
+  onApply: (config: Record<string, unknown>) => void;
+  onCancel: () => void;
+}) {
+  return (
+    <ReactFlowProvider>
+      <BuilderInner {...props} />
+    </ReactFlowProvider>
+  );
+}
+
+function BuilderInner({
+  config,
+  onApply,
+  onCancel,
+}: {
+  config: Record<string, unknown>;
+  onApply: (config: Record<string, unknown>) => void;
+  onCancel: () => void;
+}) {
+  const { screenToFlowPosition } = useReactFlow();
+  const initial = useMemo(() => canvasFromConfig(config), [config]);
+  const [services, setServices] = useState<Map<string, BuilderService>>(
+    () => new Map(initial.map((n) => [n.key, { ...n.service }])),
+  );
+  const [positions, setPositions] = useState<Record<string, { x: number; y: number }>>(
+    () => Object.fromEntries(initial.map((n) => [n.key, n.position])),
+  );
+  const [selectedKey, setSelectedKey] = useState<string | null>(null);
+
+  const flowNodes: ServiceBuilderNode[] = useMemo(
+    () =>
+      [...services.values()].map((svc) => ({
+        id: svc.key,
+        type: 'tplService' as const,
+        position: positions[svc.key] ?? { x: 0, y: 0 },
+        data: { svc },
+        selected: svc.key === selectedKey,
+      })),
+    [services, positions, selectedKey],
+  );
+
+  const flowEdges: Edge[] = useMemo(
+    () =>
+      [...services.values()].flatMap((svc) =>
+        (svc.depends_on ?? [])
+          .filter((dep) => services.has(dep))
+          .map((dep) => ({
+            id: `${dep}->${svc.key}`,
+            source: dep,
+            target: svc.key,
+            markerEnd: { type: MarkerType.ArrowClosed, width: 14, height: 14, color: 'rgba(180,227,74,0.55)' },
+            style: { stroke: 'rgba(180,227,74,0.42)', strokeWidth: 1.6 },
+            className: 'edge-premium',
+          })),
+      ),
+    [services],
+  );
+
+  const builderNodes: BuilderNode[] = useMemo(
+    () =>
+      [...services.values()].map((svc) => ({
+        key: svc.key,
+        service: svc,
+        position: positions[svc.key] ?? { x: 0, y: 0 },
+      })),
+    [services, positions],
+  );
+  const errors = useMemo(() => validateGraph(builderNodes), [builderNodes]);
+
+  const patchService = useCallback((key: string, patch: Partial<BuilderService>) => {
+    setServices((prev) => {
+      const svc = prev.get(key);
+      if (!svc) return prev;
+      const next = new Map(prev);
+      next.set(key, { ...svc, ...patch });
+      return next;
+    });
+  }, []);
+
+  const addService = useCallback((type: BuilderServiceType, position?: { x: number; y: number }) => {
+    setServices((prev) => {
+      const key = newServiceKey(type, new Set(prev.keys()));
+      const next = new Map(prev);
+      next.set(key, {
+        key,
+        type,
+        runtime: type === 'database' ? 'postgresql' : undefined,
+      });
+      setPositions((pos) => ({ ...pos, [key]: position ?? { x: 80, y: 40 + (next.size - 1) * 150 } }));
+      setSelectedKey(key);
+      return next;
+    });
+  }, []);
+
+  const removeService = useCallback((key: string) => {
+    setServices((prev) => {
+      const next = new Map(prev);
+      next.delete(key);
+      for (const svc of next.values()) {
+        svc.depends_on = svc.depends_on?.filter((d) => d !== key);
+      }
+      return next;
+    });
+    setPositions((prev) => {
+      const next = { ...prev };
+      delete next[key];
+      return next;
+    });
+    setSelectedKey((cur) => (cur === key ? null : cur));
+  }, []);
+
+  const onConnect = useCallback(
+    (conn: Connection) => {
+      if (!conn.source || !conn.target || conn.source === conn.target) return;
+      const target = services.get(conn.target);
+      if (!target) return;
+      patchService(conn.target, {
+        depends_on: [...new Set([...(target.depends_on ?? []), conn.source])],
+      });
+    },
+    [patchService, services],
+  );
+
+  const onNodesChange = useCallback(
+    (changes: NodeChange<ServiceBuilderNode>[]) => {
+      for (const ch of changes) {
+        if (ch.type === 'position' && ch.position) {
+          setPositions((prev) => ({ ...prev, [ch.id]: ch.position! }));
+        } else if (ch.type === 'remove') {
+          removeService(ch.id);
+        } else if (ch.type === 'select') {
+          if (ch.selected) setSelectedKey(ch.id);
+        }
+      }
+    },
+    [removeService],
+  );
+
+  const onEdgesChange = useCallback(
+    (changes: EdgeChange<Edge>[]) => {
+      for (const ch of changes) {
+        if (ch.type !== 'remove') continue;
+        const edge = flowEdges.find((e) => e.id === ch.id);
+        if (!edge) continue;
+        const svc = services.get(edge.target);
+        if (svc) {
+          patchService(edge.target, {
+            depends_on: (svc.depends_on ?? []).filter((d) => d !== edge.source),
+          });
+        }
+      }
+    },
+    [flowEdges, patchService, services],
+  );
+
+  const selected = selectedKey ? services.get(selectedKey) : null;
+
+  return (
+    <div className="flex min-h-0 flex-1">
+      <div className="relative flex-1">
+        <div className="absolute left-3 top-3 z-10 flex gap-1.5">
+          {(['web', 'database', 'cron', 'worker'] as const).map((t) => {
+            const meta = TYPE_META[t];
+            const Icon = meta.icon;
+            return (
+              <button
+                key={t}
+                type="button"
+                onClick={() => addService(t)}
+                className="canvas-pill inline-flex items-center gap-1.5 px-2.5 py-1.5 text-[11px] font-medium text-[var(--text-secondary)] hover:text-[var(--text-primary)]"
+              >
+                <Icon size={12} className={meta.cls} />
+                {meta.label}
+              </button>
+            );
+          })}
+        </div>
+        <ReactFlow
+          nodes={flowNodes}
+          edges={flowEdges}
+          nodeTypes={nodeTypes}
+          onNodesChange={onNodesChange}
+          onEdgesChange={onEdgesChange}
+          onConnect={onConnect}
+          onPaneClick={() => setSelectedKey(null)}
+          onDoubleClick={(e) => {
+            if ((e.target as HTMLElement).closest('.react-flow__node')) return;
+            addService('web', screenToFlowPosition({ x: e.clientX, y: e.clientY }));
+          }}
+          fitView
+          deleteKeyCode={['Backspace', 'Delete']}
+          proOptions={{ hideAttribution: true }}
+        >
+          <Background variant={BackgroundVariant.Dots} gap={22} size={1.2} color="rgba(255,255,255,0.07)" />
+        </ReactFlow>
+        <div className="canvas-pill absolute bottom-3 left-3 z-10 px-3 py-1.5 text-[10.5px] text-[var(--text-tertiary)]">
+          drag = move · connect handles = depends_on · double-click = add web · Del = remove
+        </div>
+      </div>
+
+      <div className="flex w-[290px] shrink-0 flex-col border-l border-[var(--border-subtle)]">
+        {selected ? (
+          <Inspector
+            key={selected.key}
+            svc={selected}
+            onPatch={(patch) => patchService(selected.key, patch)}
+            onRemove={() => removeService(selected.key)}
+          />
+        ) : (
+          <div className="flex flex-1 flex-col items-center justify-center gap-2 px-6 text-center">
+            <Package size={22} className="text-[var(--text-tertiary)]" />
+            <p className="text-xs text-[var(--text-tertiary)]">
+              Select a node to edit it, or add one from the toolbar.
+            </p>
+          </div>
+        )}
+        <div className="border-t border-[var(--border-subtle)] p-3">
+          {errors.length > 0 ? (
+            <div className="mb-2 max-h-[90px] overflow-y-auto rounded-[var(--radius-sm)] bg-[var(--error-soft)] px-3 py-2">
+              {errors.map((e) => (
+                <p key={e} className="text-[11px] text-[var(--error)]">• {e}</p>
+              ))}
+            </div>
+          ) : null}
+          <div className="flex gap-2">
+            <button
+              type="button"
+              onClick={onCancel}
+              className="flex-1 rounded-[var(--radius-md)] px-3 py-2 text-xs font-medium text-[var(--text-secondary)] hover:bg-[var(--surface-muted)]"
+            >
+              Back to JSON
+            </button>
+            <button
+              type="button"
+              disabled={errors.length > 0 || services.size === 0}
+              onClick={() => onApply(configFromCanvas(builderNodes, config))}
+              className="flex-1 rounded-[var(--radius-md)] bg-[var(--accent-primary)] px-3 py-2 text-xs font-semibold text-[var(--accent-on)] disabled:opacity-50"
+            >
+              Apply to JSON
+            </button>
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+const FIELD_CLS =
+  'w-full rounded-[var(--radius-sm)] border border-[var(--border-default)] bg-[var(--bg-void)] px-2.5 py-1.5 text-[12px] text-[var(--text-primary)] outline-none focus:border-[var(--accent-primary)]';
+const LABEL_CLS = 'mb-1 block text-[10.5px] font-medium uppercase tracking-wide text-[var(--text-tertiary)]';
+
+function Inspector({
+  svc,
+  onPatch,
+  onRemove,
+}: {
+  svc: BuilderService;
+  onPatch: (patch: Partial<BuilderService>) => void;
+  onRemove: () => void;
+}) {
+  const envText = Object.entries(svc.environment ?? {})
+    .map(([k, v]) => `${k}=${v}`)
+    .join('\n');
+  const volText = (svc.volumes ?? []).map((v) => `${v.source}:${v.target}${v.read_only ? ':ro' : ''}`).join('\n');
+  return (
+    <div className="flex-1 overflow-y-auto p-4">
+      <div className="mb-3 flex items-center justify-between">
+        <span className="text-[12px] font-semibold text-[var(--text-primary)]">{svc.key}</span>
+        <button
+          type="button"
+          onClick={onRemove}
+          className="flex items-center gap-1 rounded-[var(--radius-sm)] px-2 py-1 text-[11px] text-[var(--error)] hover:bg-[var(--error-soft)]"
+        >
+          <Trash2 size={12} /> Remove
+        </button>
+      </div>
+
+      <label className={LABEL_CLS}>Key</label>
+      <input className={FIELD_CLS} value={svc.key} disabled title="Key is the node id — cannot be renamed" />
+
+      <label className={`${LABEL_CLS} mt-3`}>Display name</label>
+      <input className={FIELD_CLS} value={svc.name ?? ''} onChange={(e) => onPatch({ name: e.target.value || undefined })} placeholder="optional" />
+
+      <label className={`${LABEL_CLS} mt-3`}>Type</label>
+      <select
+        className={FIELD_CLS}
+        value={svc.type}
+        onChange={(e) => onPatch({ type: e.target.value as BuilderServiceType })}
+      >
+        <option value="web">Web</option>
+        <option value="worker">Worker</option>
+        <option value="cron">Cron</option>
+        <option value="database">Database</option>
+      </select>
+
+      {svc.type === 'database' ? (
+        <>
+          <label className={`${LABEL_CLS} mt-3`}>Engine</label>
+          <select className={FIELD_CLS} value={svc.runtime ?? 'postgresql'} onChange={(e) => onPatch({ runtime: e.target.value })}>
+            {DATABASE_ENGINES.map((eng) => (
+              <option key={eng} value={eng}>{eng}</option>
+            ))}
+          </select>
+        </>
+      ) : (
+        <>
+          <label className={`${LABEL_CLS} mt-3`}>Image (runtime)</label>
+          <input className={FIELD_CLS} value={svc.runtime ?? ''} onChange={(e) => onPatch({ runtime: e.target.value || undefined })} placeholder="nginx:latest" />
+          <label className={`${LABEL_CLS} mt-3`}>Git repo</label>
+          <input className={FIELD_CLS} value={svc.repo ?? ''} onChange={(e) => onPatch({ repo: e.target.value || undefined })} placeholder="owner/repo or clone URL" />
+          {svc.repo ? (
+            <>
+              <label className={`${LABEL_CLS} mt-3`}>Branch</label>
+              <input className={FIELD_CLS} value={svc.branch ?? ''} onChange={(e) => onPatch({ branch: e.target.value || undefined })} placeholder="main" />
+              <label className={`${LABEL_CLS} mt-3`}>Build command</label>
+              <input className={FIELD_CLS} value={svc.build_command ?? ''} onChange={(e) => onPatch({ build_command: e.target.value || undefined })} />
+            </>
+          ) : null}
+          <label className={`${LABEL_CLS} mt-3`}>Start command</label>
+          <input className={FIELD_CLS} value={svc.start_command ?? ''} onChange={(e) => onPatch({ start_command: e.target.value || undefined })} />
+        </>
+      )}
+
+      {svc.type === 'web' ? (
+        <>
+          <label className={`${LABEL_CLS} mt-3`}>Port</label>
+          <input
+            className={FIELD_CLS}
+            type="number"
+            value={svc.port ?? ''}
+            onChange={(e) => onPatch({ port: e.target.value ? Number(e.target.value) : undefined })}
+          />
+          <label className={`${LABEL_CLS} mt-3`}>Health check path</label>
+          <input className={FIELD_CLS} value={svc.health_check ?? ''} onChange={(e) => onPatch({ health_check: e.target.value || undefined })} placeholder="/health" />
+        </>
+      ) : null}
+
+      <label className={`${LABEL_CLS} mt-3`}>Environment (KEY=value, one per line)</label>
+      <textarea
+        className={`${FIELD_CLS} mono min-h-[70px] resize-y`}
+        defaultValue={envText}
+        spellCheck={false}
+        onBlur={(e) => {
+          const env: Record<string, string> = {};
+          for (const line of e.target.value.split('\n')) {
+            const idx = line.indexOf('=');
+            if (idx > 0) env[line.slice(0, idx).trim()] = line.slice(idx + 1).trim();
+          }
+          onPatch({ environment: Object.keys(env).length ? env : undefined });
+        }}
+        placeholder={'DATABASE_URL={{service.db.url}}\nSECRET={{secret}}'}
+      />
+
+      <label className={`${LABEL_CLS} mt-3`}>Volumes (source:target[:ro], one per line)</label>
+      <textarea
+        className={`${FIELD_CLS} mono min-h-[50px] resize-y`}
+        defaultValue={volText}
+        spellCheck={false}
+        onBlur={(e) => {
+          const vols = e.target.value
+            .split('\n')
+            .map((l) => l.trim())
+            .filter(Boolean)
+            .map((l) => {
+              const [source, target, ro] = l.split(':');
+              return { source, target, read_only: ro === 'ro' || undefined };
+            })
+            .filter((v) => v.source && v.target);
+          onPatch({ volumes: vols.length ? vols : undefined });
+        }}
+        placeholder={'data:/var/lib/app\n./config:/etc/app:ro'}
+      />
+
+      {(svc.depends_on ?? []).length > 0 ? (
+        <div className="mt-3">
+          <span className={LABEL_CLS}>Depends on</span>
+          <div className="flex flex-wrap gap-1">
+            {svc.depends_on!.map((dep) => (
+              <span key={dep} className="inline-flex items-center gap-1 rounded-full bg-[var(--surface-muted)] px-2 py-0.5 text-[11px] text-[var(--text-secondary)]">
+                {dep}
+                <button
+                  type="button"
+                  onClick={() => onPatch({ depends_on: (svc.depends_on ?? []).filter((d) => d !== dep) })}
+                  className="text-[var(--text-tertiary)] hover:text-[var(--error)]"
+                >
+                  <X size={10} />
+                </button>
+              </span>
+            ))}
+          </div>
+        </div>
+      ) : null}
+    </div>
+  );
+}

app/frontend/src/features/templates/builder/builder-model.test.ts

@@ -0,0 +1,160 @@
+import { describe, expect, it } from 'vitest';
+import {
+  canvasFromConfig,
+  configFromCanvas,
+  layoutPositions,
+  newServiceKey,
+  validateGraph,
+  type BuilderNode,
+} from './builder-model';
+
+const plausibleConfig = {
+  version: 2,
+  services: [
+    { key: 'db', type: 'database', runtime: 'postgresql', environment: { POSTGRES_DB: 'plausible' } },
+    { key: 'events', type: 'database', runtime: 'clickhouse' },
+    {
+      key: 'web',
+      name: 'plausible',
+      type: 'web',
+      runtime: 'ghcr.io/plausible/community-edition:v2',
+      port: 8000,
+      health_check: '/api/health',
+      depends_on: ['db', 'events'],
+      environment: { DATABASE_URL: '{{service.db.url}}' },
+    },
+  ],
+};
+
+describe('canvasFromConfig', () => {
+  it('parses graph services into nodes with auto-layout', () => {
+    const nodes = canvasFromConfig(plausibleConfig);
+    expect(nodes.map((n) => n.key)).toEqual(['db', 'events', 'web']);
+    // databases are roots (depth 0), web depends on both (depth 1)
+    expect(nodes[0].position.x).toBeLessThan(nodes[2].position.x);
+    expect(nodes[1].position.y).toBeGreaterThan(nodes[0].position.y);
+  });
+
+  it('restores saved canvas positions', () => {
+    const nodes = canvasFromConfig({
+      ...plausibleConfig,
+      canvas: { positions: { db: { x: 500, y: 500 } } },
+    });
+    expect(nodes[0].position).toEqual({ x: 500, y: 500 });
+  });
+
+  it('migrates flat legacy configs to a single node', () => {
+    const nodes = canvasFromConfig({
+      type: 'web',
+      runtime: 'nginx:latest',
+      port: 80,
+      environment: { FOO: 'bar' },
+    });
+    expect(nodes).toHaveLength(1);
+    expect(nodes[0].service).toMatchObject({ key: 'app', type: 'web', runtime: 'nginx:latest', port: 80 });
+  });
+
+  it('drops entries without a key', () => {
+    const nodes = canvasFromConfig({ version: 2, services: [{ type: 'web', runtime: 'x' }, { key: 'ok', type: 'web', runtime: 'y' }] });
+    expect(nodes.map((n) => n.key)).toEqual(['ok']);
+  });
+});
+
+describe('configFromCanvas', () => {
+  it('round-trips a graph config', () => {
+    const nodes = canvasFromConfig(plausibleConfig);
+    const config = configFromCanvas(nodes, plausibleConfig);
+    const services = config.services as Record<string, unknown>[];
+    expect(config.version).toBe(2);
+    expect(services).toHaveLength(3);
+    const web = services.find((s) => s.key === 'web')!;
+    expect(web.depends_on).toEqual(['db', 'events']);
+    expect(web.port).toBe(8000);
+    expect((web.environment as Record<string, string>).DATABASE_URL).toBe('{{service.db.url}}');
+  });
+
+  it('persists node positions under config.canvas', () => {
+    const nodes = canvasFromConfig(plausibleConfig);
+    nodes[0].position = { x: 321, y: 123 };
+    const config = configFromCanvas(nodes, {});
+    expect((config.canvas as { positions: Record<string, { x: number; y: number }> }).positions.db).toEqual({ x: 321, y: 123 });
+    // and parses back to the same spot
+    expect(canvasFromConfig(config)[0].position).toEqual({ x: 321, y: 123 });
+  });
+
+  it('strips flat fields when converting a legacy config', () => {
+    const nodes = canvasFromConfig({ type: 'web', runtime: 'nginx:latest', port: 80 });
+    const config = configFromCanvas(nodes, { type: 'web', runtime: 'nginx:latest', port: 80 });
+    expect(config.type).toBeUndefined();
+    expect(config.runtime).toBeUndefined();
+    expect((config.services as unknown[]).length).toBe(1);
+  });
+});
+
+describe('layoutPositions', () => {
+  it('depths follow the depends_on chain', () => {
+    const pos = layoutPositions([
+      { key: 'a', type: 'database', runtime: 'postgresql' },
+      { key: 'b', type: 'web', runtime: 'img', depends_on: ['a'] },
+      { key: 'c', type: 'web', runtime: 'img', depends_on: ['b'] },
+    ]);
+    expect(pos.a.x).toBeLessThan(pos.b.x);
+    expect(pos.b.x).toBeLessThan(pos.c.x);
+  });
+
+  it('a dependency cycle does not hang', () => {
+    const pos = layoutPositions([
+      { key: 'a', type: 'web', runtime: 'x', depends_on: ['b'] },
+      { key: 'b', type: 'web', runtime: 'x', depends_on: ['a'] },
+    ]);
+    expect(pos.a).toBeDefined();
+    expect(pos.b).toBeDefined();
+  });
+});
+
+describe('validateGraph', () => {
+  const node = (key: string, extra: Partial<BuilderNode['service']> = {}): BuilderNode => ({
+    key,
+    position: { x: 0, y: 0 },
+    service: { key, type: 'web', runtime: 'img:1', ...extra },
+  });
+
+  it('accepts a valid graph', () => {
+    expect(validateGraph([node('db', { type: 'database', runtime: 'postgresql' }), node('web', { depends_on: ['db'] })])).toEqual([]);
+  });
+
+  it('rejects duplicate keys', () => {
+    expect(validateGraph([node('a'), node('a')])).toContain('duplicate key "a"');
+  });
+
+  it('rejects bad keys and self-deps', () => {
+    const errs = validateGraph([node('BAD KEY'), node('x', { depends_on: ['x'] })]);
+    expect(errs.some((e) => e.includes('not a valid key'))).toBe(true);
+    expect(errs).toContain('"x" depends on itself');
+  });
+
+  it('rejects deps on missing services', () => {
+    expect(validateGraph([node('web', { depends_on: ['ghost'] })])).toContain(
+      '"web" depends on unknown service "ghost"',
+    );
+  });
+
+  it('rejects database without engine and web without source', () => {
+    const errs = validateGraph([node('db', { type: 'database', runtime: undefined }), node('web', { runtime: undefined })]);
+    expect(errs).toContain('"db" is a database with no engine selected');
+    expect(errs).toContain('"web" needs an image (runtime) or a git repo');
+  });
+
+  it('reports dependency cycles', () => {
+    const errs = validateGraph([node('a', { depends_on: ['b'] }), node('b', { depends_on: ['a'] })]);
+    expect(errs.some((e) => e.startsWith('dependency cycle'))).toBe(true);
+  });
+});
+
+describe('newServiceKey', () => {
+  it('picks unused keys', () => {
+    expect(newServiceKey('database', new Set())).toBe('db');
+    expect(newServiceKey('database', new Set(['db']))).toBe('db2');
+    expect(newServiceKey('web', new Set(['web', 'web2']))).toBe('web3');
+  });
+});

app/frontend/src/features/templates/builder/builder-model.ts

@@ -0,0 +1,241 @@
+// Pure model for the visual template builder: converts between the
+// template `config` JSON (version 2 service graph, or a legacy flat
+// single-service config) and canvas state (nodes + positions), and
+// validates the graph before save. No React, no DOM — directly testable.
+
+export type BuilderServiceType = 'web' | 'worker' | 'cron' | 'database';
+
+export type BuilderService = {
+  key: string;
+  name?: string;
+  type: BuilderServiceType;
+  runtime?: string;
+  repo?: string;
+  branch?: string;
+  build_command?: string;
+  start_command?: string;
+  port?: number;
+  health_check?: string;
+  builder?: string;
+  environment?: Record<string, string>;
+  volumes?: { type?: string; source: string; target: string; read_only?: boolean }[];
+  depends_on?: string[];
+};
+
+export type BuilderCanvas = {
+  positions: Record<string, { x: number; y: number }>;
+};
+
+export type BuilderNode = {
+  key: string;
+  service: BuilderService;
+  position: { x: number; y: number };
+};
+
+const KEY_RE = /^[a-z][a-z0-9_-]*$/;
+const COL_X = 60;
+const ROW_Y = 200;
+
+function asService(raw: unknown): BuilderService | null {
+  if (!raw || typeof raw !== 'object') return null;
+  const s = raw as Record<string, unknown>;
+  const key = typeof s.key === 'string' ? s.key : '';
+  if (!key) return null;
+  const type = typeof s.type === 'string' ? s.type : 'web';
+  return {
+    key,
+    name: typeof s.name === 'string' ? s.name : undefined,
+    type: (['web', 'worker', 'cron', 'database'] as const).includes(type as BuilderServiceType)
+      ? (type as BuilderServiceType)
+      : 'web',
+    runtime: typeof s.runtime === 'string' ? s.runtime : undefined,
+    repo: typeof s.repo === 'string' ? s.repo : undefined,
+    branch: typeof s.branch === 'string' ? s.branch : undefined,
+    build_command: typeof s.build_command === 'string' ? s.build_command : undefined,
+    start_command: typeof s.start_command === 'string' ? s.start_command : undefined,
+    port: typeof s.port === 'number' ? s.port : undefined,
+    health_check: typeof s.health_check === 'string' ? s.health_check : undefined,
+    builder: typeof s.builder === 'string' ? s.builder : undefined,
+    environment:
+      s.environment && typeof s.environment === 'object' && !Array.isArray(s.environment)
+        ? Object.fromEntries(
+            Object.entries(s.environment as Record<string, unknown>).map(([k, v]) => [k, String(v)]),
+          )
+        : undefined,
+    volumes: Array.isArray(s.volumes)
+      ? (s.volumes
+          .map((v) => {
+            if (!v || typeof v !== 'object') return null;
+            const vol = v as Record<string, unknown>;
+            if (typeof vol.target !== 'string' || !vol.target) return null;
+            return {
+              type: typeof vol.type === 'string' ? vol.type : undefined,
+              source: typeof vol.source === 'string' ? vol.source : '',
+              target: vol.target,
+              read_only: typeof vol.read_only === 'boolean' ? vol.read_only : undefined,
+            };
+          })
+          .filter((v): v is NonNullable<typeof v> => v !== null)
+        )
+      : undefined,
+    depends_on: Array.isArray(s.depends_on)
+      ? s.depends_on.filter((d): d is string => typeof d === 'string')
+      : undefined,
+  };
+}
+
+// Flat legacy configs ({type, runtime, port, …} with no services array)
+// map to a single service node so the builder can edit them without
+// losing fields the round-trip would drop.
+function flatToService(config: Record<string, unknown>): BuilderService | null {
+  const type = typeof config.type === 'string' ? config.type : '';
+  const runtime = typeof config.runtime === 'string' ? config.runtime : '';
+  if (!type && !runtime) return null;
+  const svc = asService({
+    key: 'app',
+    type: type || 'web',
+    runtime,
+    port: config.port,
+    health_check: config.health_check,
+    build_command: config.build_command,
+    start_command: config.start_command,
+    environment: config.environment,
+  });
+  return svc;
+}
+
+// Layered auto-layout: depth = longest depends_on chain; column per
+// depth, row per member. Deterministic so tests can assert positions.
+export function layoutPositions(services: BuilderService[]): Record<string, { x: number; y: number }> {
+  const depth = new Map<string, number>();
+  const visiting = new Set<string>();
+  const byKey = new Map(services.map((s) => [s.key, s]));
+  const depthOf = (key: string): number => {
+    const memo = depth.get(key);
+    if (memo !== undefined) return memo;
+    if (visiting.has(key)) return 0; // cycle guard
+    visiting.add(key);
+    const deps = byKey.get(key)?.depends_on ?? [];
+    let d = 0;
+    for (const dep of deps) {
+      if (byKey.has(dep)) d = Math.max(d, depthOf(dep) + 1);
+    }
+    visiting.delete(key);
+    depth.set(key, d);
+    return d;
+  };
+  const rows = new Map<number, number>();
+  const positions: Record<string, { x: number; y: number }> = {};
+  for (const svc of services) {
+    const d = depthOf(svc.key);
+    const row = rows.get(d) ?? 0;
+    rows.set(d, row + 1);
+    positions[svc.key] = { x: COL_X + d * 300, y: 40 + row * ROW_Y };
+  }
+  return positions;
+}
+
+export function canvasFromConfig(config: Record<string, unknown>): BuilderNode[] {
+  const canvas = (config.canvas ?? {}) as Partial<BuilderCanvas>;
+  const saved = canvas.positions ?? {};
+  const rawServices = Array.isArray(config.services) ? config.services : null;
+  const services = rawServices
+    ? rawServices.map(asService).filter((s): s is BuilderService => s !== null)
+    : [];
+  if (services.length === 0) {
+    const flat = flatToService(config);
+    if (flat) services.push(flat);
+  }
+  const auto = layoutPositions(services);
+  return services.map((service) => ({
+    key: service.key,
+    service,
+    position: saved[service.key] ?? auto[service.key] ?? { x: COL_X, y: 40 },
+  }));
+}
+
+export function configFromCanvas(
+  nodes: BuilderNode[],
+  rest: Record<string, unknown>,
+): Record<string, unknown> {
+  const services = nodes.map((node) => {
+    const svc = node.service;
+    const out: Record<string, unknown> = { key: svc.key, type: svc.type };
+    if (svc.name) out.name = svc.name;
+    if (svc.runtime) out.runtime = svc.runtime;
+    if (svc.repo) out.repo = svc.repo;
+    if (svc.branch) out.branch = svc.branch;
+    if (svc.build_command) out.build_command = svc.build_command;
+    if (svc.builder) out.builder = svc.builder;
+    if (svc.start_command) out.start_command = svc.start_command;
+    if (svc.port) out.port = svc.port;
+    if (svc.health_check) out.health_check = svc.health_check;
+    if (svc.environment && Object.keys(svc.environment).length > 0) out.environment = svc.environment;
+    if (svc.volumes && svc.volumes.length > 0) out.volumes = svc.volumes;
+    if (svc.depends_on && svc.depends_on.length > 0) out.depends_on = svc.depends_on;
+    return out;
+  });
+  const positions: Record<string, { x: number; y: number }> = {};
+  for (const node of nodes) positions[node.key] = node.position;
+  const restConfig = { ...rest };
+  // Flat (v1) fields and stale graph keys are dropped — the graph wins.
+  for (const k of ['type', 'runtime', 'build_command', 'start_command', 'port', 'health_check', 'environment', 'dockerfile', 'nixpacks_config', 'services', 'canvas']) {
+    delete restConfig[k];
+  }
+  return {
+    version: 2,
+    ...restConfig,
+    services,
+    canvas: { positions },
+  };
+}
+
+export function validateGraph(nodes: BuilderNode[]): string[] {
+  const errors: string[] = [];
+  const keys = new Set<string>();
+  for (const node of nodes) {
+    if (!KEY_RE.test(node.service.key)) {
+      errors.push(`"${node.service.key || '(empty)'}" is not a valid key (lowercase, digits, - or _)`);
+    }
+    if (keys.has(node.service.key)) errors.push(`duplicate key "${node.service.key}"`);
+    keys.add(node.service.key);
+    if (node.service.type === 'database' && !node.service.runtime) {
+      errors.push(`"${node.service.key}" is a database with no engine selected`);
+    }
+    if (node.service.type !== 'database' && !node.service.runtime && !node.service.repo) {
+      errors.push(`"${node.service.key}" needs an image (runtime) or a git repo`);
+    }
+  }
+  for (const node of nodes) {
+    for (const dep of node.service.depends_on ?? []) {
+      if (dep === node.service.key) errors.push(`"${dep}" depends on itself`);
+      else if (!keys.has(dep)) errors.push(`"${node.service.key}" depends on unknown service "${dep}"`);
+    }
+  }
+  // Cycle detection — a cycle makes topo sort fail at deploy time.
+  const state = new Map<string, 0 | 1 | 2>();
+  const byKey = new Map(nodes.map((n) => [n.service.key, n]));
+  const visit = (key: string, trail: string[]): void => {
+    const s = state.get(key) ?? 0;
+    if (s === 2) return;
+    if (s === 1) {
+      errors.push(`dependency cycle: ${[...trail, key].join(' → ')}`);
+      return;
+    }
+    state.set(key, 1);
+    for (const dep of byKey.get(key)?.service.depends_on ?? []) {
+      if (byKey.has(dep)) visit(dep, [...trail, key]);
+    }
+    state.set(key, 2);
+  };
+  for (const node of nodes) visit(node.service.key, []);
+  return errors;
+}
+
+export function newServiceKey(type: BuilderServiceType, existing: Set<string>): string {
+  const base = type === 'database' ? 'db' : type;
+  if (!existing.has(base)) return base;
+  let i = 2;
+  while (existing.has(`${base}${i}`)) i += 1;
+  return `${base}${i}`;
+}

app/frontend/src/features/templates/pages/TemplatesPage.tsx

@@ -1,4 +1,4 @@
-import { useMemo, useState } from 'react';
+import { lazy, Suspense, useMemo, useState } from 'react';
 import { Link, useSearchParams } from 'react-router-dom';
 import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
 import {
@@ -42,6 +42,10 @@ import {
   Network,
 } from 'lucide-react';
 
+const TemplateBuilder = lazy(() =>
+  import('@/features/templates/builder/TemplateBuilder').then((m) => ({ default: m.TemplateBuilder })),
+);
+
 function toServiceName(value: string): string {
   const normalized = value
     .toLowerCase()
@@ -127,6 +131,7 @@ export function TemplatesPage() {
   const isAdmin = Boolean(profileQuery.data?.isAdmin);
 
   const [editorOpen, setEditorOpen] = useState(false);
+  const [editorMode, setEditorMode] = useState<'json' | 'visual'>('json');
   const [editorJson, setEditorJson] = useState(EMPTY_TEMPLATE_JSON);
   const [editingTemplate, setEditingTemplate] = useState<TemplateEntity | null>(null);
   const [editorIsPublic, setEditorIsPublic] = useState(false);
@@ -1022,17 +1027,50 @@ export function TemplatesPage() {
       {/* Template editor — JSON only */}
       {editorOpen ? (
         <div className="fixed inset-0 z-50 flex items-center justify-center bg-black/60 p-4 backdrop-blur-sm">
-          <div className="flex max-h-[90vh] w-full max-w-2xl flex-col overflow-hidden rounded-[var(--radius-lg)] border border-[var(--border-subtle)] bg-[var(--bg-base)] shadow-2xl">
+          <div className={`flex max-h-[92vh] w-full flex-col overflow-hidden rounded-[var(--radius-lg)] border border-[var(--border-subtle)] bg-[var(--bg-base)] shadow-2xl ${editorMode === 'visual' ? 'max-w-6xl' : 'max-w-2xl'}`}>
             <div className="flex items-center justify-between border-b border-[var(--border-subtle)] px-5 py-4">
               <div>
                 <h2 className="text-[15px] font-semibold text-[var(--text-primary)]">
                   {editingTemplate ? `Edit ${editingTemplate.name}` : 'New template'}
                 </h2>
                 <p className="text-xs text-[var(--text-tertiary)]">
-                  JSON definition — name, category, config and variables.
+                  {editorMode === 'visual'
+                    ? 'Visual builder — drop service nodes, wire depends_on edges, apply back to JSON.'
+                    : 'JSON definition — name, category, config and variables.'}
                 </p>
               </div>
               <div className="flex items-center gap-2">
+                <div className="mr-1 inline-flex overflow-hidden rounded-[var(--radius-md)] border border-[var(--border-default)]">
+                  {(['json', 'visual'] as const).map((mode) => (
+                    <button
+                      key={mode}
+                      type="button"
+                      onClick={() => {
+                        if (mode === 'visual' && editorMode === 'json') {
+                          try {
+                            const parsed = JSON.parse(editorJson);
+                            if (!parsed || typeof parsed.config !== 'object') {
+                              setEditorError('Visual mode needs a valid JSON body with a "config" object first.');
+                              return;
+                            }
+                          } catch {
+                            setEditorError('Fix the JSON before switching to visual mode.');
+                            return;
+                          }
+                          setEditorError(null);
+                        }
+                        setEditorMode(mode);
+                      }}
+                      className={`px-3 py-1.5 text-[11px] font-medium capitalize ${
+                        editorMode === mode
+                          ? 'bg-[var(--surface-muted)] text-[var(--text-primary)]'
+                          : 'text-[var(--text-tertiary)] hover:text-[var(--text-primary)]'
+                      }`}
+                    >
+                      {mode}
+                    </button>
+                  ))}
+                </div>
                 <label className="inline-flex cursor-pointer items-center gap-1.5 rounded-[var(--radius-md)] border border-[var(--border-default)] px-3 py-1.5 text-xs font-medium text-[var(--text-secondary)] hover:text-[var(--text-primary)]">
                   <Upload size={12} /> Upload .json
                   <input
@@ -1055,12 +1093,49 @@ export function TemplatesPage() {
                 </button>
               </div>
             </div>
-            <textarea
+            {editorMode === 'visual' ? (
-              value={editorJson}
+              <div className="flex min-h-[520px] flex-1 flex-col">
-              onChange={(e) => setEditorJson(e.target.value)}
+                <Suspense
-              spellCheck={false}
+                  fallback={
-              className="mono min-h-[380px] flex-1 resize-none bg-[var(--bg-void)] p-4 text-[12.5px] leading-relaxed text-[var(--text-secondary)] outline-none"
+                    <div className="flex flex-1 items-center justify-center text-[var(--text-tertiary)]">
-            />
+                      <Loader2 size={20} className="animate-spin" />
+                    </div>
+                  }
+                >
+                  {(() => {
+                    let cfg: Record<string, unknown> = {};
+                    try {
+                      const parsed = JSON.parse(editorJson) as { config?: Record<string, unknown> };
+                      cfg = parsed?.config ?? {};
+                    } catch {
+                      cfg = {};
+                    }
+                    return (
+                      <TemplateBuilder
+                        config={cfg}
+                        onCancel={() => setEditorMode('json')}
+                        onApply={(newConfig) => {
+                          try {
+                            const parsed = JSON.parse(editorJson) as Record<string, unknown>;
+                            setEditorJson(JSON.stringify({ ...parsed, config: newConfig }, null, 2));
+                          } catch {
+                            setEditorJson(JSON.stringify({ config: newConfig }, null, 2));
+                          }
+                          setEditorMode('json');
+                        }}
+                      />
+                    );
+                  })()}
+                </Suspense>
+              </div>
+            ) : (
+              <textarea
+                value={editorJson}
+                onChange={(e) => setEditorJson(e.target.value)}
+                spellCheck={false}
+                className="mono min-h-[380px] flex-1 resize-none bg-[var(--bg-void)] p-4 text-[12.5px] leading-relaxed text-[var(--text-secondary)] outline-none"
+              />
+            )}
             {composeWarnings.length > 0 ? (
               <div className="border-t border-[var(--border-subtle)] bg-[var(--warning-soft)]/60 px-5 py-2.5 text-xs text-[var(--warning)]">
                 <p className="font-medium mb-1">Compose import notes</p>
@@ -1074,7 +1149,7 @@ export function TemplatesPage() {
                 {editorError}
               </div>
             ) : null}
-            <div className="flex items-center justify-between border-t border-[var(--border-subtle)] px-5 py-3.5">
+            <div className={`flex items-center justify-between border-t border-[var(--border-subtle)] px-5 py-3.5 ${editorMode === 'visual' ? 'hidden' : ''}`}>
               <label className="inline-flex cursor-pointer items-center gap-2 text-[11px] text-[var(--text-secondary)]">
                 <input
                   type="checkbox"