CircuitCraft Architecture
Hybrid AI Pipeline
Circuit craft main page
Clarification flow
Architecture flow
Deterministic design rule check
Structured plan flow
Code/Code block flow

CircuitCraft — Project Story

Inspiration

Hardware engineering is inherently unforgiving. When you are an undergraduate or a self-taught hobbyist in Nigeria, frying a microcontroller isn't just a quick swap from a lab cabinet — it is a costly mistake that can derail a project for weeks while you source replacement parts.

We watched classmates and early professionals face a brutal gap. They would start with a great idea — "I want to build a motion-triggered alarm" — but immediately hit a wall of decisions:

Which microcontroller should I use?
Do these sensors conflict on pins?
What's my power budget?

Forums are overwhelming, and most tutorials assume you already made all the key decisions. The result: beginners burn hours on preventable mistakes — wrong pin assignments, voltage mismatches, power budget overruns — often discovering the error only after buying the parts and wiring the circuit.

We wanted to build a "second brain" that acts as a mentor: AI that helps you reason through complex tradeoffs, while strict deterministic rules keep your hardware safe.

What It Does: The CircuitCraft Framework

CircuitCraft is an AI-powered execution framework and visual integrated development environment (IDE). It is designed to structure the decisions that a first-time hardware builder simply doesn't know how to make. The platform guides the user through five distinct, carefully controlled stages:

1. Clarify (Intent Extraction): The user describes their project idea in natural language. Instead of immediately generating an answer, the AI acts as a mentor, asking targeted clarifying questions with suggested answers. It accumulates context across conversational turns until the project's goal, physical constraints, and missing information are fully resolved.
2. Compare (Architectural Reasoning): The AI proposes exactly two architecturally different solutions (e.g., an Arduino Uno prioritized for simplicity versus an ESP32 prioritized for WiFi capability). Crucially, the AI explicitly outlines the tradeoffs for each option across cost, portability, complexity, and power consumption. The AI proposes, but the user must read both and make the final call.
3. Validate (Safety Check): Once the user selects an architecture, the system runs it through a deterministic Design Rule Check (DRC) engine. This stage has zero AI involvement. The DRC checks 9+ named electrical rules. Results are surfaced as actionable violations (e.g., conflicts or warnings). The user must explicitly acknowledge all warnings to pass the approval gate.
4. Build (Visual & Code Generation): The validated architecture automatically scaffolds a visual block editor powered by Google Blockly, populating it with pre-wired hardware blocks and correct pin assignments. As the user edits, extends, or rebuilds their logic visually, a custom code generator writes validated Arduino C++ in real-time in a synchronized Monaco editor.
5. Plan (Execution Roadmap): Finally, the AI generates a structured, 4–5 milestone execution plan tailored precisely to the user's chosen components, giving them a clear path from their digital workspace to a physical prototype.

How We Built It: A Hybrid Architecture

Our core thesis was to use AI exactly where natural language understanding is required — interpreting vague ideas and generating explanations — and to use deterministic rules everywhere correctness is non-negotiable. To achieve this, we divided the architecture to play to our team's specific strengths:

The AI & Language Layer

David spearheaded our machine learning integrations. We utilized Google Gemini 2.0 Flash (leveraging its native Schema API for reliable structured JSON output) as our primary model, with OpenAI GPT-4o and Anthropic Claude Opus 4.5 integrated as runtime-selectable alternatives. The LLMs handle all the "fuzzy" logic: extracting the user's unstructured intent, comparing architectural tradeoffs, and structuring open-ended milestone plans.

The Deterministic Backend & Infrastructure

Sam architected the full-stack infrastructure and our safety engines. We explicitly removed the LLM from making hardware decisions. Pin assignments are managed by a deterministic greedy algorithm (resolvePinAssignments()) that runs against a static, curated Component Specification table. All safety validation is offloaded entirely to the local DRC engine to guarantee electrical compatibility.

The Frontend & User Experience

As the project manager and UI/UX designer, I focused on translating this complex dual-engine logic into an intuitive interface. We built the frontend using React 19 and Zustand for state management, styling it with Tailwind CSS. The challenge was making the transition from the AI's abstract suggestions to the hard, real-time C++ code feel seamless, structured, and entirely under the user's control.

The Challenges We Faced

1. Making LLM Output Safe Enough for Hardware

Large language models are prone to hallucination. They can confidently return plausible-sounding JSON that fails structural validation, or worse, recommend component combinations that are electrically incompatible (e.g., connecting a 5V sensor to a 3.3V GPIO pin). In software, a bad output throws an error; in hardware, it destroys components.

To prevent malformed data from silently corrupting the application state, we wrapped every LLM call in a strict Zod runtime schema validation loop. If the AI's output fails the schema check, the system intercepts it and automatically retries once with a targeted error-correction prompt containing the specific Zod failure signature. If it fails a second time, it throws a clean, user-visible HTTP 422 error.

2. Mathematical Hardware Validation (The DRC Engine)

Because we cannot trust generative AI with physics, we had to build the DRC engine to programmatically enforce 9 named rules (VR-001 through VR-009). This required complex deterministic logic.

For example, to enforce Rule VR-003 (Current Budget Overrun), the engine must mathematically verify that the total current draw of all AI-recommended components does not exceed the absolute limit of the selected microcontroller's regulator before the user is allowed to proceed:

$$\sum_{i=1}^{n} I_{\text{draw}}(c_i) \leq I_{\text{max}}(\text{board})$$

Where $I_{\text{draw}}(c_i)$ represents the current requirement of each individual component in the array, and $I_{\text{max}}(\text{board})$ is the absolute current limit of the board. If this equation fails, the system hard-blocks progression.

3. Integrating Google Blockly (Imperative) into React (Declarative)

Blockly is an imperative DOM library that directly manipulates the Document Object Model, which fundamentally conflicts with React's declarative virtual DOM framework. During Vite's hot module replacement (HMR) in development, React would re-mount the component while the Blockly instance persisted in the DOM. This caused severe workspace stacking, floating toolboxes rendering in the wrong positions, and complete coordinate system corruption.

We solved this architectural conflict by creating a module-level singleton (workspaceRef.ts) to manage the live WorkspaceSvg reference. By keeping the mutable DOM object entirely outside of the React and Zustand lifecycles, and implementing a custom coordinate conversion algorithm, we stabilized the visual editor.

Accomplishments That We're Proud Of

The Deterministic DRC Engine: We successfully abstracted critical electronics engineering principles into a completely deterministic engine that catches and isolates AI hallucinations before they ever reach the user's physical hardware.
Provider Flexibility: We engineered a unified schema validation wrapper that seamlessly abstracts Gemini's native Schema API, OpenAI's JSON objects, and Anthropic's prompt-based JSON. This allows the application to swap flagship models at runtime without altering the downstream behavior of the IDE.
Strict Human-in-the-Loop Gates: We successfully implemented a system where the AI never acts as the final authority. The AI proposes architectures, but the system hard-stops to force the human user to read the tradeoffs, acknowledge the hardware risks, and explicitly approve the validation warnings.

What We Learned

Building CircuitCraft taught us that the most powerful AI tools are not the ones that attempt to automate everything. By explicitly restricting the Large Language Models from making final safety validations, assigning pins, or generating unverified code, we actually created a significantly more trustworthy and useful application.

We learned how to successfully bridge the gap between generative language models and strict mathematical rules, proving that AI is most effective in engineering when used as a structured decision-support system, rather than a blind generator.