Build Creately

0%0 of 16 items done

Saved on this device only. Tick prerequisites first, then work the phases in order · do not start one until the checks above it pass.

A structured diagramming tool where the hard part is not drawing but routing: connectors that find their way around shapes, stay attached when things move, and keep a large diagram readable, plus shapes that hold data so a diagram can be a view of something rather than a picture.

estimated effort multi-daythe files for this build are in the project pack

CanvasA scene graph with shapes, ports and connectors as first-class objectsRoutingOrthogonal routing with obstacle avoidanceLayoutAutomatic arrangement as an option, never as a surpriseDataShapes with typed fields and views derived from themRuntimeTypeScript with a local application and file-based documents

Before step 1

Everything below is assumed from the first step. Tick each one when you actually have it, not when you plan to.

installfree
Why Runs the application and the routing.
Get it nodejs.org, or nvm install 22. open ↗
Verify node --version prints v22 or higher
installfree
Why Orthogonal routing with obstacle avoidance is a real algorithm and writing it from nothing while also building an editor is two projects.
Get it A library or a well-understood algorithm for grid-based routing with obstacle costs.
Verify A path routes around a rectangle with two bends
have readyfree
Why Routing quality, bend counts and canvas performance are all uninteresting on a diagram of ten shapes and become the entire problem at eighty.
Get it Recreate a real system diagram you have, or import one from an existing tool.
Verify Eighty shapes exist with connectors that cross and compete for space
have readyfree
Why Data-driven styling cannot be evaluated without real data whose values actually vary, and the interesting case is data that changes between imports.
Get it A file with a key per shape and fields that would drive colour, imported twice with changes between.
Verify A second import updates shapes rather than duplicating them

Data model

Create these before the first phase that stores anything. Changing a table later is the expensive kind of change.

- documents(id, name, canvas_json, updated_at)
- shapes(id, document_id, kind, x, y, width, height, style_json, data_json)
- ports(shape_id, name, side, offset) · connectors attach to ports, not to coordinates
- connectors(id, document_id, from_port, to_port, route_kind, waypoints_json, label, manual_route)
- shape_fields(document_id, kind, field_name, field_type) · the schema for a shape kind's data
- views(id, document_id, filter_json, style_rules_json) · styling driven by data rather than set by hand
- A connector records whether its route was set manually, because automatic rerouting must never discard a route someone drew deliberately.

Environment variables

These go in a .env file the app reads at startup. The pack's .env.example is this table as a file · copy it, never commit the filled-in version.

Variable	Needed	Example	Where the value comes from
`DOCUMENTS_DIR`	required	`~/Documents/diagrams`	Diagram files. A diagram is a document and should behave like one.
`ROUTE_BEND_PENALTY`	required	`10`	How strongly bends are avoided. High, because readability beats path length.
`ROUTE_TIMEOUT_MS`	required	`16`	Routing runs on drag. Beyond this it must fall back rather than stutter.
`AUTO_LAYOUT_ON_CHANGE`	required	`never`	Present as a constant. Placement often carries meaning a layout algorithm cannot see.
`PRESERVE_MANUAL_ROUTES`	required	`always`	An hour of readability work should survive a shape being nudged.
`MAX_SHAPES_WARNING`	required	`500`	Where canvas performance starts to degrade, made explicit rather than discovered.

The build, in order

1
Connectors that stay attached
Moving a shape takes its connectors with it.
1. The single decision the rest of the build depends on.
  Files src/ports.ts
2. On move and on resize, both.
  Files src/connectors.ts
3. A stated rule, not dangling references.
  Files src/delete.ts
done when · tick each as it passes
watch out
- Attaching a connector to the coordinate where it was drawn means every shape move leaves lines pointing at empty space, and on a diagram of any size the cleanup takes longer than the drawing did. Bind to ports and recompute the endpoint from the shape's current geometry.
next phase
2
Routing around things
Connectors avoid shapes rather than passing through them.
1. Passing through a shape is what makes diagrams unreadable.
  Files src/route.ts
2. Eleven bends is correct and useless. Two is the target.
  Files src/route.tssrc/route.test.ts
3. A hundred shapes, recomputed on drag. Measure it.
  Files src/route.ts
done when · tick each as it passes
watch out
- Routing that finds the shortest obstacle-free path will happily produce a connector with eleven bends that is technically correct and unreadable. Penalise bends heavily, prefer a slightly longer path with two, and accept crossing another connector rather than adding turns.
next phase
3
Respecting a route someone drew
Automatic rerouting never discards a manual adjustment.
1. An hour of readability work should survive a nudge.
  Files src/connectors.ts
2. Rather than silently replacing them.
  Files src/route.ts
3. Available, deliberate, never a side effect.
  Files src/connectors.ts
done when · tick each as it passes
watch out
- Rerouting everything on every change discards the adjustments someone made to get a complex diagram readable, which is often an hour of work, and it happens the instant they nudge one shape. Mark manual routes, preserve them, and surface the ones a change has genuinely broken.
next phase
4
Shapes that carry data
A diagram can be a view of information rather than a picture of it.
1. Validated on entry, like any schema.
  Files src/fields.ts
2. So colour means something and updates when the data does.
  Files src/style-rules.ts
3. By a key, not by position. Duplicating on every import is the failure.
  Files src/import.ts
done when · tick each as it passes
watch out
- Styling set by hand looks the same as styling derived from data until the data changes, at which point the diagram is confidently wrong and nobody can tell which colours mean something. Derive styling from rules where data exists, and make manually styled shapes visually distinguishable in editing.
5
Layout, export and large diagramsproduct builder
Automatic arrangement helps when asked, and the diagram exports cleanly.
1. Placement often carries meaning that a layout algorithm cannot see.
  Files src/layout.ts
2. So a diagram can be searched, edited and read by assistive tools.
  Files src/export.ts
3. Five hundred shapes. Measure pan and zoom, do not assume.
  Files src/canvas.ts
done when · tick each as it passes
watch out
- Running automatic layout on open, or after an edit, destroys deliberate placement that carried meaning, and undo often does not restore it exactly. Make layout something you invoke, applied with a preview, and always undoable in one step.

what this build does not replace

Real-time collaboration.
Large shape libraries.
Reverse engineering from code or infrastructure.
Presentation and animation.
large template libraries
high-fidelity import and export
presentation and enterprise controls
multiplayer cursors and comments

after v1, if you want it

Swimlanes and containers, which change routing constraints considerably
A data panel showing the diagram as a table, since some questions are easier answered there
Diff between two versions of a diagram, which is what makes them reviewable

Need the files? The project pack on the verdict page hands your agent the whole brief · more whiteboards.