Circuit Checkups with a Graph Database: How CircuitDoctor Catches Wiring Errors Early

In circuit design, a seemingly reasonable schematic can hide problems like power-to-ground shorts, displays missing power, or reversed signal pins. For electronics beginners, locating these errors often requires tracing connections and understanding how components relate—a steep barrier. Developer Nayanjyoti built CircuitDoctor during the Graph Hacks hackathon, using the FalkorDB graph database to help users check KiCad circuit wiring issues before connecting hardware.

The circuit itself is a graph

The core insight behind CircuitDoctor is straightforward: circuits are naturally suited to graph modeling. Components have pins, and pins connect via nets. In FalkorDB, this relationship is represented as Component ──HAS_PIN──> Pin ──ON_NET──> Net. Each uploaded circuit generates its own graph, making it easy to compare versions before and after modifications.

For supported two-pin resistors, the system also creates a THROUGH relationship between pins, allowing path queries to trace connections through resistors. Shared nets and passing through components are two distinct relationship types, and the model represents them separately to avoid confusion. This modeling approach makes subsequent connectivity queries natural and efficient.

Netlist and the KiCad file format

CircuitDoctor processes .net files, which are netlist files in electronic design automation (EDA). They describe the connections between components and their pins in text form, without the physical layout or package details of components. KiCad, an open-source EDA tool, typically exports netlists from schematics, including component identifiers, pin numbers, and net names. CircuitDoctor parses the netlist to derive the "component–pin–net" graph structure, so it can only verify logical connections—it cannot know actual PCB routing or component internal circuits. Understanding the difference between a netlist, a schematic, and a PCB layout helps clarify the tool's boundaries: a netlist is an abstraction of connections and does not describe current paths or signal integrity.

What FalkorDB does behind the scenes

FalkorDB provides the connection data for CircuitDoctor's checks and explanations. Queries identify pins sharing the same net and, combined with verified component information, flag supported wiring conflicts, including power-to-ground shorts and voltage rail conflicts.

After a user selects two pins, Cypher's shortestPath query searches for a path over ON_NET and THROUGH relationships; if a route is found, it is highlighted on the circuit diagram. Additionally, the app uses algo.WCC (weakly connected components) to identify isolated groups in the circuit structure graph—isolated groups aren't necessarily faults, but they can alert users to places worth checking.

For supported boards and displays, additional checks cover power, ground, and I2C connections. These features run on the uploaded circuit rather than being tied to a predefined example.

Cypher query language and graph algorithms

Cypher is a declarative query language for property graph databases, using ASCII-art-like pattern matching syntax, e.g., (a)-[:ON_NET]->(b) means two nodes are connected via an ON_NET relationship. shortestPath is a built-in Cypher path-finding function that searches for the shortest path between two nodes over specified relationship types. algo.WCC refers to the Weakly Connected Components algorithm, which partitions mutually reachable nodes into separate subgraphs. In a circuit context, WCC groups pins connected through wires or resistors, helping identify electrically isolated modules. These query capabilities allow CircuitDoctor to quickly locate critical paths and group structures without traversing all connections.

Making query results understandable

Getting connection data is only half the job; presenting it clearly is equally important. Raw query results are useful during development, but when checking a circuit, users need to know which connection matters and where to find it.

CircuitDoctor displays detected issues alongside an interactive circuit diagram, letting users highlight relevant pins and trace routes without reading database output. Gemini provides conversational exploration: when users ask how two pins connect or request an explanation of a warning, Gemini calls tools to query the circuit in FalkorDB and then explains the result using the returned evidence. The goal is to make explanations traceable to the user's own files.

Gemini's function calling mechanism

Gemini's conversational explanations rely on tool calling: when a user asks questions like "how do these two pins connect," the model does not generate an answer from thin air. Instead, it generates a structured query request, calls a predefined tool function (here, an interface to query FalkorDB), obtains the connection evidence returned by the graph database, and then organizes a natural-language explanation based on that evidence. This pattern combines the LLM's reasoning with the graph database's precise queries, avoiding hallucinations while making every explanation traceable to the user's uploaded netlist data. Tool call parameters and results are typically exchanged in JSON, and the model decides whether further queries are needed or it can answer directly.

Verifying that fixes work

After modifying a circuit, users can upload the updated .net file. Both versions are checked in separate FalkorDB graphs, and Python then compares the findings and connection data, showing which warnings have cleared, which remain, whether new warnings appeared, and which connections changed.

This introduces a key interface challenge: the circuit diagram and status must describe the same version. Viewing an earlier circuit should show its original findings, while viewing the updated circuit should show the revised connections and results. Without this consistency, users will be confused even if the comparison logic is correct. The site also offers a pair of downloadable example files so users can experience the full workflow without first creating a KiCad project.

Lessons from building

Graph queries make connectivity problems easier to express—shared connections, routes between pins, and isolated groups all fit the model well. Another lesson is that relationships should be prepared at the right stage: CircuitDoctor creates resistor traversal links at upload time, keeping path-finding as a read operation.

Visual clarity requires separate investment. Highlighting a line is only useful if the user can follow it and read the surrounding labels, so the circuit view and comparison flow need to be polished in sync with the checking logic. The most important lesson is distinguishing facts from assumptions: the netlist tells the app which pins are connected, but it doesn't describe all internal details of physical modules, nor can it prove how a module will behave once powered.

Defining the tool's boundaries

CircuitDoctor is a wiring checker: it doesn't simulate current, measure resistance, or model component timing. General connection exploration uses the uploaded graph, while component-specific checks depend on identified parts and verified specifications, currently supporting Arduino Uno R3, the classic Nano, and some displays. Connection tracing follows wires and supported resistors and does not infer internal paths through every component.

Clearing a warning means the corresponding check no longer finds that issue in the revised file, but it does not guarantee the complete physical circuit will work. The developer used AI coding assistants such as Codex and Claude Code to build it, validated the implementation with automated tests and browser checks, and the article itself was drafted and edited with AI assistance.

Future plans include expanding component coverage, but this version focuses on one useful workflow: upload a circuit, understand connections, check issues, and verify a revised file. For KiCad users, CircuitDoctor offers a lightweight way to catch wiring pitfalls before powering up.

The difference between circuit simulation and wiring checks

Circuit simulation tools (such as SPICE) predict voltage, current, and timing behavior by solving component equations, requiring component model parameters and excitation signals; wiring checks only verify that connections in the netlist conform to design rules or expected topology, without numerical computation. CircuitDoctor explicitly does not simulate current or measure resistance, meaning it cannot catch issues like wrong resistor values, insufficient power supply, or signal timing conflicts. What it excels at is structural errors: power-to-ground shorts, reversed pins, missing power nets. Treating wiring checks as a static rule-verification step in the design flow, rather than a simulation substitute, helps users correctly interpret "clearing warnings"—it only means the connection logic is correct within the scope of the checks, not that the circuit will function properly.

One-line Summary

CircuitDoctor uses the FalkorDB graph database to check KiCad circuit wiring, catching shorts, missing power, and other pitfalls before power-up.

Paragraph Summary

CircuitDoctor is a tool built by a developer at the Graph Hacks hackathon to help electronics beginners check KiCad circuit wiring errors before connecting hardware. Its core idea is to model circuits as graphs: components connect pins via HAS_PIN relationships, pins connect to nets via ON_NET, and resistors get an extra THROUGH relationship to support path traversal. FalkorDB provides queries like shortestPath and weakly connected components to trace connections, detect power-to-ground shorts, and find voltage rail conflicts. Gemini uses tool calling to query the graph database and explain connections using the returned evidence. The tool supports uploading revised netlists for version comparison and clearly defines its boundaries: it does not simulate current or guarantee the physical circuit will work.