Hear the Short Before You Smell It: Building CircuitDoctor with FalkorDB

Nayanjyoti Das — Sun, 18 Oct 2026 18:04:50 +0000

I'm Nayanjyoti from India, and for Graph Hacks by WeMakeDevs and FalkorDB, I built CircuitDoctor: a tool that helps students and makers inspect wiring in KiCad circuits before connecting their hardware.

You upload a .net file, explore the circuit, inspect supported wiring warnings, and ask questions about its connections. After changing the wiring in KiCad, you can upload the revised file to see what changed.

Live app: CircuitDoctor
Source code: GitHub
Demo video: Watch the walkthrough
Track: Agents That Act on Connected Data

The problem I wanted to solve

A schematic can look reasonable while still containing a connection you didn't intend. Power and ground might share a net. A display might be missing a supply connection. Two signal pins might be swapped.

Finding these problems means following connections and understanding how different parts relate to each other. For someone still learning electronics, even figuring out where to look can be difficult.

I wanted CircuitDoctor to make that process easier: explain the finding, show the relevant wiring, and let the user investigate further.

A circuit is already a graph

The graph model came naturally. Components have pins, and pins connect through nets. In FalkorDB, CircuitDoctor represents this as:

Component ──HAS_PIN──> Pin ──ON_NET──> Net

Each uploaded circuit gets its own graph. This keeps different uploads separate and lets the application retain both versions when comparing a circuit before and after a change.

For supported two-pin resistors, CircuitDoctor also creates THROUGH relationships between their pins. That allows a path query to follow a connection through a resistor.

Sharing a net and passing through a component are different relationships, so the model represents them separately.

What FalkorDB actually does

FalkorDB provides the connection data behind CircuitDoctor's checks and explanations.

Queries identify pins that share a net. Combined with verified information about recognized components, this allows the application to flag supported wiring conflicts, including power-to-ground shorts and conflicting voltage rails.

For connection tracing, the user selects two pins. A Cypher shortestPath query searches through ON_NET and THROUGH relationships. If it finds a route, CircuitDoctor highlights it on the drawing.

The application also uses algo.WCC to identify separate groups in the circuit's structural graph. A separate group is not necessarily a fault, but it can help a user notice something worth inspecting.

For supported boards and displays, additional checks inspect power, ground, and I2C connections.

These features work from the uploaded circuit. They are not tied to one predefined example.

Making the answers understandable

Getting the connection data was only part of the work. Presenting it clearly mattered just as much.

During development, raw query results are useful. When checking a circuit, though, a user needs to understand which connection matters and where to find it.

CircuitDoctor displays findings alongside an interactive circuit drawing. Users can highlight relevant pins and trace routes without reading the underlying database output.

Gemini adds a conversational way to explore the same information. A user can ask how two pins are connected or ask for an explanation of a warning. Gemini calls tools that query the uploaded circuit in FalkorDB, then uses the returned evidence to explain the result.

The goal is to make the explanation traceable to the user's file. The graph provides the facts the assistant can work with.

Checking whether a fix helped

I also wanted the workflow to continue after the first warning.

Once a user changes their circuit, they can upload the updated .net file. Both versions are checked using their separate FalkorDB graphs. Python then compares the findings and connection data.

The comparison shows which warnings cleared, which remain, whether new warnings appeared, and which wires changed.

This introduced an important interface challenge: the drawing and status must describe the same version. Viewing the earlier circuit should show its original findings. Viewing the updated circuit should show the revised connections and results.

Without that consistency, even a correct comparison can be confusing.

The website includes a downloadable pair of example files so people can try this workflow without first creating a KiCad project. Those files use the same upload and checking process as other circuits.

What I learned while building it

Graph queries made questions about connectivity easier to express. Shared connections, routes between pins, and separate groups all fit the model well.

I also learned to prepare relationships at the right stage. CircuitDoctor creates resistor traversal links during upload, so looking up a route can remain a read operation.

Another lesson was that visual clarity needs its own attention. Highlighting a wire is useful only when the user can follow it and read the labels around it. The circuit view and comparison flow needed work alongside the checks themselves.

The most important lesson was to separate facts from assumptions. A netlist tells the application which pins are connected. It does not describe every internal detail of a physical module or prove how that module will behave when powered.

Keeping the scope clear

CircuitDoctor is a wiring inspection tool. It does not simulate current, measure resistance, or model component timing.

General connection exploration uses the uploaded graph. Component-specific checks depend on recognized parts and verified specifications, including support for Arduino Uno R3, classic Nano, and selected displays. Connection tracing follows wires and supported resistors; it does not infer internal paths through every component.

A cleared warning means the corresponding check no longer finds that issue in the revised file. It does not guarantee that the complete physical circuit will work.

I built CircuitDoctor with help from AI coding assistants, including Codex and Claude Code, and verified the implementation through automated tests and browser checks. I also used AI assistance to help draft and edit this article.

There is more I would like to add, especially broader component coverage. For this version, I focused on making one workflow useful: upload a circuit, understand its connections, inspect a problem, and check the revised file.

If you use KiCad, you can try CircuitDoctor, watch the demo, and explore the implementation on GitHub.

DEV Community: Nayanjyoti Das

Hear the Short Before You Smell It: Building CircuitDoctor with FalkorDB