Building Circuit Diagram Maker: Architecture Case Study

Building Circuit Diagram Maker: the engineering problem

A circuit diagram editor has to preserve meaning while users manipulate a picture. Moving a component changes its geometry, but its wire connections must still refer to the intended terminals. Panning should change the view, not the saved drawing. Exporting should produce a usable document without selection handles or temporary simulation highlights. These boundaries make a seemingly simple drawing product a substantial software architecture problem.

This case study examines the Circuit Diagram Maker source snapshot at revision 2ec0f3d, dated August 19, 2026, reviewed on September 9, 2026. The evidence includes its editor types, coordinate utilities, wire-update functions, history store, diagram controller, export implementation and simulation worker, plus the project's control-simulation compatibility document. It is a source-based engineering account, not a claim about measured revenue, customer adoption or conversion improvement.

We distinguish observed implementation from recommended checks throughout. Reading a function establishes what that code expresses; it does not prove every production interaction succeeds or that a simulator accurately represents every physical device. The illustrations are conceptual editorial assets, not screenshots of the product. The focus is what a founder or technology leader can learn about building a dependable browser-based specialist tool.

Model components and connections as separate concepts

In the reviewed source, a placed component has an identity, a symbol key, coordinates, rotation and flip state, alongside labels and other metadata. The symbol definition supplies reusable geometry and pin information. This separates an instance on a drawing from the definition it refers to. Two resistors can share a symbol while remaining distinct objects with different positions, labels and connected wires.

A wire stores both endpoint identities and visible segments. Its start and end each refer to a component and a pin; the segments describe the route between them. That distinction is central to editing. A line that happens to touch a shape is not necessarily a valid connection, while a wire can remain logically attached as its visible route changes. The model gives routing code an explicit relationship to preserve.

This design also exposes important failure cases. A saved wire may refer to a component or pin that is no longer available. In the reviewed recalculation function, missing endpoint components, symbols or pins cause it to return the existing segments. That is an observed fallback, not evidence that the connection remains valid. A responsible product review should ask how the interface communicates unresolved references and how imports or migrations validate them.

For another visual product, the equivalent distinction might be a workflow edge versus its curved path, or a floor-plan object versus its screen rectangle. Decide which relationships have domain meaning before choosing a renderer. If those relationships exist only as pixels or incidental overlap, later features such as validation, export and collaborative editing become harder to reason about.

Model concern	Evidence in the reviewed source	Engineering implication
Component instance	Identity, symbol key, position and orientation	Reuse symbol definitions without merging object identity
Wire connection	Component and pin identifiers at both ends	Preserve the intended relationship while rerouting
Wire appearance	Segment list, colour and label	Change presentation without redefining the connection
Viewport	Pan values and zoom factor	Keep navigation separate from drawing coordinates
Document revision	Server version and optional expected version	Detect a stale save when the caller supplies its revision

Keep screen coordinates out of the document model

The editor's coordinate utility converts between canvas and screen positions using a viewport with horizontal pan, vertical pan and zoom. Its screen-to-canvas calculation subtracts pan and divides by zoom; the reverse calculation multiplies by zoom and adds pan. The canvas event handlers also subtract the element's screen offset before passing pointer coordinates to that utility. Together these operations connect browser input to document geometry.

Consider a simplified example with a canvas point at horizontal coordinate 100, zoom of two and horizontal pan of 30. Its screen position relative to the canvas element is 230: 100 multiplied by two, then increased by 30. Converting 230 back subtracts 30 and divides by two, returning 100. If the element begins 50 pixels from the viewport's left edge, the browser pointer coordinate is 280; that element offset must first be removed.

The numbers are explanatory inputs, not a performance measurement or a description of a particular user's session. The point is the invariant: changing the view must not change the stored component position. A test can transform a range of document points to screen coordinates and back, allowing a small tolerance for floating-point arithmetic. Dragging after pan and zoom should preserve the same relationship.

The rendered editor uses an SVG group with translation and scaling. MDN's SVG transformation guide explains the underlying transformation concepts. The product lesson is to define and reuse the coordinate contract across dragging, selection, connectors and overlays. A locally correct formula in one interaction does not prevent another interaction from applying offsets in a different order.

Reroute wires from resolved pins and current obstacles

The reviewed wire-update function first resolves the two component instances and their symbol definitions. It looks up the referenced pins, then calculates their positions using component location, rotation and horizontal or vertical flips. Routing from those resolved ports makes orientation part of the connection calculation instead of assuming that a pin remains at its original unrotated position.

Other components become routing obstacles through their rotated bounding boxes. The two directly connected components are excluded from that general obstacle list, while their own bounds are passed separately to the port-routing function. The result is a new segment route between the endpoints. The source describes obstacle-aware routing, but this review does not establish global optimality, a maximum drawing size or successful routing for every arrangement.

The companion update function limits recalculation to wires attached to the component identities being changed. Unaffected wires are returned unchanged. This is a useful separation of responsibilities: one function decides which connections require attention, while another resolves the geometry of an individual connection. It also provides a focused place to test whether moving one object accidentally alters an unrelated wire.

A meaningful routing test set should include rotated and flipped components, tightly spaced obstacles, a missing symbol and a connection with an unresolved pin. It should also verify endpoint attachment after the move, not merely count the resulting segments. A route can look plausible while ending at the wrong terminal. Those are recommended acceptance checks; this article does not claim that every one was executed during the source review.

Treat undo as document behaviour rather than a cosmetic button

The editor store captures history entries containing components, wires, annotations, images, connectors and further document state. It copies those structures when recording a history entry. Before appending a new entry it trims the history after the current position, so an edit following an undo creates a new branch of the working history instead of keeping an incompatible redo future.

Undo and redo move a history index and restore captured state. The reviewed code also clears the current selection and marks the document dirty. These details matter because a restored drawing may no longer contain the objects that were selected, and a local reversal still needs to be saved. The history has a configured maximum; this article does not assign a capacity value without inspecting that setting and its surrounding behaviour.

Copying complete snapshots is straightforward to understand, but it raises questions about memory use and document size. An alternative based on commands or patches introduces different complexity around inverses, dependencies and migrations. There is no universal winner. A technology review should measure representative drawings and editing patterns before replacing an understandable implementation with a more elaborate history mechanism.

Test the sequence that users actually rely on: create connected objects, move one, undo, redo, undo again and make a different edit. Verify the restored connection identities, geometry and document state at each step. For multi-sheet documents, check what switching sheets means for history. The important result is a coherent editing experience, not simply that the undo button changes something on screen.

Distinguish local history, autosave and durable recovery

An undo stack is not a server-side backup. The reviewed diagram update controller checks edit permission, validates submitted fields and performs its update inside a database transaction with a row lock. If a caller supplies an expected version that differs from the current document version, the controller returns a conflict response with the current version and document data rather than silently applying that stale update.

There is an important limit: the expected-version field is optional in the reviewed endpoint. The conflict check therefore depends on the caller providing it. It would be inaccurate to claim that every possible request is protected from lost updates merely because the controller contains a comparison. A complete review follows the client save path, tests concurrent requests and checks how the interface presents a conflict to the user.

Successful updates increment the document version. The controller also requests a persistence checkpoint when document content or the relevant title state changes. That is a separate concern from the transient browser history. A useful recovery design should explain what survives a reload, a browser crash, a conflicting save and a server storage failure, rather than presenting all four as the same “saved” state.

The source also separates a diagram save from its thumbnail. The thumbnail endpoint checks edit permission, validates and sanitises the submitted SVG, and returns a specific storage-failure response that explains the diagram remains saved. This is a concrete example of useful failure boundaries: losing a preview should not force the interface to misreport the status of the underlying document.

Make exports independent of the editing session

The SVG export function clones the rendered SVG and removes its viewport transform. It then removes several categories of interface-only elements, including rulers, minimap elements, pin overlays and objects explicitly marked to be skipped during export. Selected wire appearance is restored from stored wire-colour data, so a temporary selection accent does not become the published drawing colour.

The code resolves CSS variables and calculates a content bounding box with padding before setting the standalone SVG dimensions and view box. It also considers the selected canvas background. These steps address a common failure in browser exports: an image looks correct inside the application because it inherits surrounding styles, then opens differently when removed from that environment.

The repository includes a test file that renders the real editor canvas and exports its SVG to check selection and overlay behaviour. That is stronger evidence of intended integration coverage than a test of a string-building helper alone. This article reviewed the test source; it does not claim a fresh execution of the entire Circuit Diagram Maker suite or independent certification of all exported formats.

For a release gate, open exported files outside the application and compare selected versus unselected drawings, panned versus unpanned views, and documents with different backgrounds. Confirm that transient simulation overlays are absent when they should be. A downloadable file is only a successful export if the resulting artifact carries the intended information without depending on the editor's current state.

Keep simulation execution and visual feedback distinct

The reviewed simulation worker receives a run request, executes a simulation job and sends progress, result or error messages carrying the request identity. This makes the message contract visible rather than embedding all computation directly in a component event handler. MDN's Web Workers documentation explains how workers communicate through messages and operate without direct access to the document's DOM.

A worker boundary alone is not proof of responsiveness. Serialising a large document, updating charts or processing too many progress messages can still consume time elsewhere. A complete performance investigation needs representative inputs and traces. It should also check what happens when a user changes the circuit while an earlier request is still running, so an old result is not mistaken for the state of the new drawing.

Circuit Diagram Maker's separate control-simulation compatibility document describes a deterministic functional tester with explicit supported devices and behaviours. It states that AI is not in that execution path and distinguishes functional state from detailed physical modelling. For example, it does not equate a motor running-state indication with a calculation of torque, heating or mechanical load. Those limits are part of the documented product contract.

That distinction matters to product positioning. A convincing animation can suggest more physical fidelity than the model provides. The interface, documentation and sales copy should use the same supported-behaviour definitions. This case study discusses software boundaries; it does not establish electrical safety, design compliance or suitability for constructing a real installation. Domain validation must be appropriate to the actual intended use.

Use explicit compatibility instead of visual inference

The project's compatibility document requires custom parts to have stable terminal identities, terminal mappings and a supported behavioural definition before they can be treated as simulatable. It also describes reviewed definitions and expected state vectors. The architectural lesson is that a recognisable picture, a label or a three-dimensional shape is insufficient evidence of executable behaviour.

This principle generalises beyond circuit software. A workflow icon does not define its authorisation rules, and a chart label does not establish the provenance of its values. Keep the domain contract explicit and make unsupported states visible. If a future AI feature proposes a component or mapping, treat that proposal as input to validation rather than an automatic extension of the simulator's supported semantics.

The compatibility document further describes simulation state as transient and says topology edits reset stale state. That is the right question for any analysis tool: which changes invalidate the previous result? Record those dependencies deliberately. Otherwise a user may continue viewing an apparently authoritative output after modifying the assumptions that produced it, even though the computational engine itself behaved correctly.

Turn architectural boundaries into a reviewable release gate

A founder does not need to read every routing function to ask useful questions. Request a compact evidence pack covering the main user journey: create a diagram, connect components, edit it, save it, reload it and export it. Include representative failure states. The pack should identify the tested source revision, environment and limitations, so a screenshot or passing test cannot be mistaken for a broader claim.

The following table is a proposed review checklist derived from the source analysis. It is not a statement that all checks passed in this review. Its purpose is to connect each product promise to observable behaviour and make remaining uncertainty visible before release. Add domain-specific verification wherever the product makes claims about the meaning or accuracy of engineering output.

Product promise	A useful acceptance check	Evidence to retain
Editing preserves connections	Move and rotate connected components	Endpoint identities and resulting geometry
Navigation preserves the drawing	Pan and zoom before editing and export	Stable document coordinates and artifact comparison
Undo restores coherent state	Undo, redo and branch into a new edit	Full state assertions across the sequence
Saves handle stale work	Submit conflicting versioned updates	Conflict response and understandable client recovery
Exports stand alone	Open output outside the editor	Rendered artifact with no interface overlays
Analysis reports its limits	Use an unsupported model and change topology	Visible compatibility state and invalidated old results

What this case tells a technology leader

The reviewed implementation provides concrete examples of separating domain identity, geometry, presentation, persistence and analysis. Each separation creates a place to state a contract and test it. It also reveals where a claim needs qualification: preserved wire segments are not validated connectivity, an optional version check is not universal conflict protection, and a functional simulation is not a complete physical model.

For a comparable product, begin with the user action whose failure would cause the most harm or rework. Trace its data through these boundaries and ask what happens when an assumption fails. Use a software architecture review to turn that investigation into specific evidence and decisions. The strongest case for an architecture is what it makes understandable and verifiable, together with an honest account of what remains unproven.