Two different JSON shapes for the same diagram. Why?

[rhengles]

Six issues found integrating drawDB via the extension hooks

Ref: 8f4fe78 (main) · All line numbers verified against that commit.

Context: we deploy drawDB under a sub-path (https://example.com/schema/) with a custom
persistence layer built on ExtensionsContext (cloudSave / cloudLoad). Everything below
was hit in that setup, but items 1–3 and 6 affect the stock app too.

Each item is independent; happy to send PRs for any subset — just say which shape you'd prefer.

---

1. Three different JSON shapes for the same diagram

Three keys differ depending on which code path produced the object:

concept	A editor state / IndexedDB diagrams / cloudSave	B file export, share/gist, IndexedDB templates	C "export saved data" backup
relationships	references	relationships	relationships
subject areas	areas	subjectAreas	subjectAreas
diagram name	name	title	name

It isn't an "internal vs external" split: both A and B are persisted to IndexedDB —
db.diagrams stores A, db.templates stores B — and both are produced by user-facing save
actions.

Produces A

• src/components/Workspace.jsx#L113-L117 — buildCloudPayload()
• src/components/Workspace.jsx#L177-L181, #L201-L204 — save() → db.diagrams
• src/components/EditorHeader/ControlPanel.jsx#L842, #L901 — cloud save payloads

Produces B

• src/components/EditorHeader/ControlPanel.jsx#L1326-L1347 — File → Export → JSON
• src/components/EditorHeader/ControlPanel.jsx#L1014-L1030 — Save as template → db.templates
• src/components/EditorHeader/Modal/Share.jsx#L74-L76 — gist payload
• src/templates/template1.js#L288, #L346, #L348 — bundled templates

Consumes A

• src/components/Workspace.jsx#L302 — applyDiagramState() reads diagram.references

Consumes B

• src/components/Workspace.jsx#L373-L374 — loadTemplate() reads template.relationships / subjectAreas
• src/components/Workspace.jsx#L395-L397 — loadFromGist() reads parsed.relationships / subjectAreas
• src/components/EditorHeader/Modal/Modal.jsx#L104-L109 — overwriteDiagram() reads importData.relationships / subjectAreas / title

loadDiagram and loadTemplate sit ~70 lines apart in the same file and read different keys
for the same concept.

Consequence for integrators: cloudSave hands over shape A, but the importer requires
shape B (src/data/schemas.js#L212: required: ["tables", "relationships", "notes", "subjectAreas"],
checked by src/utils/validateSchema.js#L4-L10). Persisting exactly what cloudSave provides
produces a file drawDB itself cannot import. Round-tripping cloudSave → file → import is
impossible without an undocumented rename.

2. exportSavedData does half the conversion and leaks storage bookkeeping

src/utils/exportSavedData.js#L7-L16:

const formatDiagram = (diagram) => {
  const formattedDiagram = { ...diagram };
  formattedDiagram.relationships = diagram.references;
  formattedDiagram.subjectAreas = diagram.areas;
  delete formattedDiagram.references;
  delete formattedDiagram.areas;
  return formattedDiagram;
};

Two problems:

• It renames references and areas but leaves name, while the file format uses
  title — that's shape C above. Files from this path are missing their title on
  re-import: Modal.jsx#L108 only calls setTitle if (importData.title).
• It spreads the raw Dexie row, so the backup files carry id, diagramId, lastModified
  and loadedFromGistId — storage bookkeeping in a file meant to be re-imported. The id in
  particular is a stale auto-increment key from another database.
  This is also the only place in the codebase where the two shapes are explicitly reconciled,
  and it exists solely for the backup ZIP.

3. Import reports a shape problem as a database mismatch

src/components/EditorHeader/Modal/ImportDiagram.jsx:

• #L53-L69 — shape validation runs first, but on failure only calls setError and returns
• #L71-L83 — the database check compares against the currently open diagram and reports
  "The imported diagram and the open diagram don't use matching databases."
• #L85 — jsonObject.relationships.forEach(...), which throws on shape A
  Because the database check is what surfaces in the UI, a file that is simply in the wrong
  shape is reported as a database mismatch. Two unrelated causes, one message. We lost real
  time to this: the file was valid MySQL, and the actual problem was the open diagram sitting
  on GENERIC (see issue 5).

Suggested fix: report the schema-validation failure with its own message, and say which
properties are missing.

4. Four window.open calls use absolute paths, breaking sub-path deployments

file	call	menu entry
src/components/EditorHeader/Modal/Modal.jsx#L266	window.open("/editor/templates/" + selectedTemplateId, "_blank")	File → New
src/components/EditorHeader/ControlPanel.jsx#L969	window.open("/editor", "_blank")	File → New window
src/components/EditorHeader/ControlPanel.jsx#L1742	window.open("/bug-report", "_blank")	Help → Report a bug
src/pages/Templates.jsx#L25	window.open("/editor/templates/" + id, "_blank")	template gallery

These bypass both Vite's base and React Router's basename. Served under /schema/, File →
New navigates to /editor/templates/blank at the site root, which is not the app.

Note the contrast: the navigate(...) calls with absolute paths (e.g.
ControlPanel.jsx#L1065, Workspace.jsx#L155) work fine, because they go through the router.
Only the window.open calls escape it.

Fix would be prefixing import.meta.env.BASE_URL, or routing these through the router where a
new tab isn't required.

5. A missing diagram leaves the editor with no way to choose a database

With <WorkSpace forcedDiagramId="…" />, load() goes straight to loadDiagram():

• src/components/Workspace.jsx#L344-L346 — const { diagram } = await fetchDiagram(id); if (!diagram) return;
  The "choose a database" modal only exists in the branch without a forced id:

• src/components/Workspace.jsx#L420-L424 — if (!loadedDiagramId) { … if (selectedDb === "") setShowSelectDbModal(true); … }
  So when the backing store has no diagram yet — a first run, or any cloudLoad returning
  null — the editor silently keeps the default GENERIC
  (src/context/DiagramContext.jsx#L13) with no UI affordance to change it. Importing a MySQL
  file then fails with the message from issue 3, and File → New doesn't help: it re-enters the
  same path and hits the same return.

Suggested fix: show the database selector when a forced-id load finds nothing, or let the
integrator supply a default database.

6. load() is called without error handling

• src/components/Workspace.jsx#L503-L507:

useEffect(() => {
  document.title = "Editor | drawDB";
  load();
}, [load]);

load() calls extensions.cloudLoad(id) (src/components/Workspace.jsx#L290). A rejected promise there — an auth error,
a network failure — becomes an unhandled rejection. The editor stays blank on GENERIC, with
nothing in the UI indicating that loading failed, and the next symptom is the misleading
import error from issue 3.

extensions.cloudSave is handled carefully by comparison
(src/components/Workspace.jsx#L151-L167, including the 402 case). A .catch on load() that surfaces the failure would match.

---

Questions

1. Is the shape split in issue 1 intentional — say, B as a stable interchange format and A as
   internal? If so, db.templates storing B while db.diagrams stores A seems to cut across
   that line, and exportSavedData producing C cuts across it again.
2. Would you accept a PR normalizing on one shape, with a compatibility read for the other so
   existing files and IndexedDB records keep working?
3. If a full normalization is too invasive, would you take the smaller pieces separately —
   the conversion as a shared exported helper (1, 2), the import error ordering (3), the
   BASE_URL prefix (4), the database selector on empty forced-id load (5), and the .catch
   on load() (6)?

[1ilit]

1. the different shapes aren't intentional. this is technical debt i've been too lazy to address
2. yep
3. it is invasive, so smaller pieces are more convenient for validating