# vulpfin/vulpfin-circuitsmith architecture

> Architecture diagram of the GitHub repository vulpfin/vulpfin-circuitsmith, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vulpfin/vulpfin-circuitsmith
- Repository: https://github.com/vulpfin/vulpfin-circuitsmith

## Overview

VFCS is a visual logic-to-hardware workbench. The main workflow is to compose a circuit in the web editor, simulate its behavior, then package it as a reusable chip or pursue physical-part mapping and HDL/format export. The graph includes the editor’s chip and truth-table capabilities, the simulation engine and its logic/library layers, and the physical mapping and integration branches. Some UI composition and downstream package interactions are documented but not visible in sampled calls; those links are marked dashed where needed.

Main entry points: [`apps/web/src/App.tsx`](https://github.com/vulpfin/vulpfin-circuitsmith/blob/main/apps/web/src/App.tsx) (Workbench), [`packages/sim-core/src/engine.ts`](https://github.com/vulpfin/vulpfin-circuitsmith/blob/main/packages/sim-core/src/engine.ts) (Simulation Engine), [`packages/exporters/src/index.ts`](https://github.com/vulpfin/vulpfin-circuitsmith/blob/main/packages/exporters/src/index.ts) (Circuit Exporters), [`apps/web/src/lib/truthTableImport.ts`](https://github.com/vulpfin/vulpfin-circuitsmith/blob/main/apps/web/src/lib/truthTableImport.ts) (Truth Table Import)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_editor["Circuit Editor"]
  node_app["Workbench<br/>[App.tsx]"]
  node_palette["Component Palette"]
  node_canvas["Workspace Canvas"]
  node_inspector["Circuit Inspector<br/>[InspectorPanel.tsx]"]
  node_status["Simulation Status<br/>[StatusPanel.tsx]"]
  node_truthimport["Truth Table Import"]
  node_truthpanel["Import Panel"]
  node_chipdesigner["Chip Designer<br/>[chipDesigner.ts]"]
  node_chiplibrary["Chip Library"]
  node_chipvisual["Chip Visual Layer"]
  node_nodepins["Pin Resolution<br/>[nodePins.ts]"]
  node_chipsvisuals["Chip Visuals<br/>[chipVisuals.ts]"]
  node_nodesizing["Node Sizing<br/>[nodeSizing.ts]"]
end

subgraph group_simulation["Logic Simulation"]
  node_simulation["Simulation Engine<br/>[engine.ts]"]
  node_logic["Logic Operations<br/>[logic.ts]"]
  node_nodelibrary["Node Definitions<br/>[library.ts]"]
end

subgraph group_hardware["Hardware Outputs"]
  node_exporters["Circuit Exporters<br/>[index.ts]"]
  node_verilog["Verilog Export<br/>[verilog.ts]"]
  node_ligic["Ligic JSON Export<br/>[ligic-json.ts]"]
  node_kicad["KiCad Export Stub<br/>[kicad.ts]"]
  node_partmapping["Part Mappings<br/>[mappings.ts]"]
  node_partdb[("Part Database<br/>[database.ts]")]
  node_integrations["Integration Adapters<br/>[index.ts]"]
end

subgraph group_foundation["Shared Model"]
  node_model["Circuit Data Model<br/>[index.ts]"]
end

node_engineer(("Circuit Designer"))
node_digikey["DigiKey Search"]

node_engineer -->|"edits circuit"| node_app
node_app -->|"runs simulation"| node_simulation
node_app -->|"searches parts"| node_integrations
node_app -.->|"imports truth table"| node_truthimport
node_app -->|"builds chip pins"| node_chipdesigner
node_app -->|"resolves pins"| node_nodepins
node_app -->|"sizes nodes"| node_nodesizing
node_truthpanel -.->|"accepts imports"| node_truthimport
node_chiplibrary -->|"uses chip design"| node_chipdesigner
node_chipvisual -->|"renders visuals"| node_chipsvisuals
node_nodepins -->|"normalizes visuals"| node_chipsvisuals
node_chipsvisuals -->|"uses node size"| node_nodesizing
node_truthimport -->|"clamps layout"| node_nodesizing
node_simulation -->|"resolves drivers"| node_logic
node_simulation -->|"uses definitions"| node_nodelibrary
node_app -.->|"exports circuits"| node_exporters
node_app -.->|"maps components"| node_partmapping
node_partmapping -->|"looks up parts"| node_partdb
node_app -->|"requests search"| node_digikey
node_integrations -.->|"uses part data"| node_partdb
node_exporters -.->|"exports HDL"| node_verilog
node_exporters -.->|"exports JSON"| node_ligic
node_exporters -.->|"offers placeholder"| node_kicad
node_simulation -.->|"evaluates circuit"| node_model
node_verilog -.->|"reads circuit data"| node_model
node_truthimport -->|"builds circuit data"| node_model
node_partmapping -.->|"defines mappings"| node_model

click node_app "https://github.com/vulpfin/vulpfin-circuitsmith/blob/main/apps/web/src/App.tsx"
click node_palette "https://github.com/vulpfin/vulpfin-circuitsmith/blob/main/apps/web/src/components/ComponentPalette.tsx"
click node_canvas "https://github.com/vulpfin/vulpfin-circuitsmith/blob/main/apps/web/src/components/WorkspaceCanvas.tsx"
click node_inspector "https://github.com/vulpfin/vulpfin-circuitsmith/blob/main/apps/web/src/components/InspectorPanel.tsx"
click node_status "https://github.com/vulpfin/vulpfin-circuitsmith/blob/main/apps/web/src/components/StatusPanel.tsx"
click node_truthimport "https://github.com/vulpfin/vulpfin-circuitsmith/blob/main/apps/web/src/lib/truthTableImport.ts"
click node_truthpanel "https://github.com/vulpfin/vulpfin-circuitsmith/blob/main/apps/web/src/components/TruthTableImportPanel.tsx"
click node_chipdesigner "https://github.com/vulpfin/vulpfin-circuitsmith/blob/main/apps/web/src/lib/chipDesigner.ts"
click node_chiplibrary "https://github.com/vulpfin/vulpfin-circuitsmith/blob/main/apps/web/src/components/ChipLibraryPanel.tsx"
click node_chipvisual "https://github.com/vulpfin/vulpfin-circuitsmith/blob/main/apps/web/src/components/ChipVisualLayer.tsx"
click node_nodepins "https://github.com/vulpfin/vulpfin-circuitsmith/blob/main/apps/web/src/lib/nodePins.ts"
click node_chipsvisuals "https://github.com/vulpfin/vulpfin-circuitsmith/blob/main/apps/web/src/lib/chipVisuals.ts"
click node_nodesizing "https://github.com/vulpfin/vulpfin-circuitsmith/blob/main/apps/web/src/lib/nodeSizing.ts"
click node_simulation "https://github.com/vulpfin/vulpfin-circuitsmith/blob/main/packages/sim-core/src/engine.ts"
click node_logic "https://github.com/vulpfin/vulpfin-circuitsmith/blob/main/packages/sim-core/src/logic.ts"
click node_nodelibrary "https://github.com/vulpfin/vulpfin-circuitsmith/blob/main/packages/sim-core/src/library.ts"
click node_model "https://github.com/vulpfin/vulpfin-circuitsmith/blob/main/packages/circuit-model/src/index.ts"
click node_exporters "https://github.com/vulpfin/vulpfin-circuitsmith/blob/main/packages/exporters/src/index.ts"
click node_verilog "https://github.com/vulpfin/vulpfin-circuitsmith/blob/main/packages/exporters/src/verilog.ts"
click node_ligic "https://github.com/vulpfin/vulpfin-circuitsmith/blob/main/packages/exporters/src/ligic-json.ts"
click node_kicad "https://github.com/vulpfin/vulpfin-circuitsmith/blob/main/packages/exporters/src/kicad.ts"
click node_partmapping "https://github.com/vulpfin/vulpfin-circuitsmith/blob/main/packages/part-mapper/src/mappings.ts"
click node_partdb "https://github.com/vulpfin/vulpfin-circuitsmith/blob/main/packages/part-mapper/src/database.ts"
click node_integrations "https://github.com/vulpfin/vulpfin-circuitsmith/blob/main/packages/integrations/src/index.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_palette,node_canvas,node_inspector,node_status,node_truthimport,node_truthpanel,node_chipdesigner,node_chiplibrary,node_chipvisual,node_nodepins,node_chipsvisuals,node_nodesizing toneBlue
class node_simulation,node_logic,node_nodelibrary toneAmber
class node_exporters,node_verilog,node_ligic,node_kicad,node_partmapping,node_partdb,node_integrations toneMint
class node_model toneRose
class node_engineer,node_digikey toneIndigo
```

## Components

### Circuit Editor

- [Workbench](https://github.com/vulpfin/vulpfin-circuitsmith/blob/main/apps/web/src/App.tsx): `apps/web/src/App.tsx`
- [Component Palette](https://github.com/vulpfin/vulpfin-circuitsmith/blob/main/apps/web/src/components/ComponentPalette.tsx): `apps/web/src/components/ComponentPalette.tsx`
- [Workspace Canvas](https://github.com/vulpfin/vulpfin-circuitsmith/blob/main/apps/web/src/components/WorkspaceCanvas.tsx): `apps/web/src/components/WorkspaceCanvas.tsx`
- [Circuit Inspector](https://github.com/vulpfin/vulpfin-circuitsmith/blob/main/apps/web/src/components/InspectorPanel.tsx): `apps/web/src/components/InspectorPanel.tsx`
- [Simulation Status](https://github.com/vulpfin/vulpfin-circuitsmith/blob/main/apps/web/src/components/StatusPanel.tsx): `apps/web/src/components/StatusPanel.tsx`
- [Truth Table Import](https://github.com/vulpfin/vulpfin-circuitsmith/blob/main/apps/web/src/lib/truthTableImport.ts): `apps/web/src/lib/truthTableImport.ts`
- [Import Panel](https://github.com/vulpfin/vulpfin-circuitsmith/blob/main/apps/web/src/components/TruthTableImportPanel.tsx): `apps/web/src/components/TruthTableImportPanel.tsx`
- [Chip Designer](https://github.com/vulpfin/vulpfin-circuitsmith/blob/main/apps/web/src/lib/chipDesigner.ts): `apps/web/src/lib/chipDesigner.ts`
- [Chip Library](https://github.com/vulpfin/vulpfin-circuitsmith/blob/main/apps/web/src/components/ChipLibraryPanel.tsx): `apps/web/src/components/ChipLibraryPanel.tsx`
- [Chip Visual Layer](https://github.com/vulpfin/vulpfin-circuitsmith/blob/main/apps/web/src/components/ChipVisualLayer.tsx): `apps/web/src/components/ChipVisualLayer.tsx`
- [Pin Resolution](https://github.com/vulpfin/vulpfin-circuitsmith/blob/main/apps/web/src/lib/nodePins.ts): `apps/web/src/lib/nodePins.ts`
- [Chip Visuals](https://github.com/vulpfin/vulpfin-circuitsmith/blob/main/apps/web/src/lib/chipVisuals.ts): `apps/web/src/lib/chipVisuals.ts`
- [Node Sizing](https://github.com/vulpfin/vulpfin-circuitsmith/blob/main/apps/web/src/lib/nodeSizing.ts): `apps/web/src/lib/nodeSizing.ts`

### Logic Simulation

- [Simulation Engine](https://github.com/vulpfin/vulpfin-circuitsmith/blob/main/packages/sim-core/src/engine.ts): `packages/sim-core/src/engine.ts`
- [Logic Operations](https://github.com/vulpfin/vulpfin-circuitsmith/blob/main/packages/sim-core/src/logic.ts): `packages/sim-core/src/logic.ts`
- [Node Definitions](https://github.com/vulpfin/vulpfin-circuitsmith/blob/main/packages/sim-core/src/library.ts): `packages/sim-core/src/library.ts`

### Hardware Outputs

- [Circuit Exporters](https://github.com/vulpfin/vulpfin-circuitsmith/blob/main/packages/exporters/src/index.ts): `packages/exporters/src/index.ts`
- [Verilog Export](https://github.com/vulpfin/vulpfin-circuitsmith/blob/main/packages/exporters/src/verilog.ts): `packages/exporters/src/verilog.ts`
- [Ligic JSON Export](https://github.com/vulpfin/vulpfin-circuitsmith/blob/main/packages/exporters/src/ligic-json.ts): `packages/exporters/src/ligic-json.ts`
- [KiCad Export Stub](https://github.com/vulpfin/vulpfin-circuitsmith/blob/main/packages/exporters/src/kicad.ts): `packages/exporters/src/kicad.ts`
- [Part Mappings](https://github.com/vulpfin/vulpfin-circuitsmith/blob/main/packages/part-mapper/src/mappings.ts): `packages/part-mapper/src/mappings.ts`
- [Part Database](https://github.com/vulpfin/vulpfin-circuitsmith/blob/main/packages/part-mapper/src/database.ts): `packages/part-mapper/src/database.ts`
- [Integration Adapters](https://github.com/vulpfin/vulpfin-circuitsmith/blob/main/packages/integrations/src/index.ts): `packages/integrations/src/index.ts`

### Shared Model

- [Circuit Data Model](https://github.com/vulpfin/vulpfin-circuitsmith/blob/main/packages/circuit-model/src/index.ts): `packages/circuit-model/src/index.ts`

### Other components

- **Circuit Designer**
- **DigiKey Search**

## Connections

- Circuit Designer → Workbench: edits circuit (evidence: `README.md`)
- Workbench → Simulation Engine: runs simulation (evidence: `apps/web/src/App.tsx`)
- Workbench → Integration Adapters: searches parts (evidence: `apps/web/src/App.tsx`)
- Workbench → Truth Table Import: imports truth table (evidence: `apps/web/src/App.tsx`)
- Workbench → Chip Designer: builds chip pins (evidence: `apps/web/src/App.tsx`)
- Workbench → Pin Resolution: resolves pins (evidence: `apps/web/src/App.tsx`)
- Workbench → Node Sizing: sizes nodes (evidence: `apps/web/src/App.tsx`)
- Import Panel → Truth Table Import: accepts imports (evidence: `README.md`)
- Chip Library → Chip Designer: uses chip design (evidence: `apps/web/src/components/ChipLibraryPanel.tsx`)
- Chip Visual Layer → Chip Visuals: renders visuals (evidence: `apps/web/src/components/ChipVisualLayer.tsx`)
- Pin Resolution → Chip Visuals: normalizes visuals (evidence: `apps/web/src/lib/nodePins.ts`)
- Chip Visuals → Node Sizing: uses node size (evidence: `apps/web/src/lib/chipVisuals.ts`)
- Truth Table Import → Node Sizing: clamps layout (evidence: `apps/web/src/lib/truthTableImport.ts`)
- Simulation Engine → Logic Operations: resolves drivers (evidence: `packages/sim-core/src/engine.ts`)
- Simulation Engine → Node Definitions: uses definitions (evidence: `packages/sim-core/src/engine.ts`)
- Workbench → Circuit Exporters: exports circuits (evidence: `README.md`)
- Workbench → Part Mappings: maps components (evidence: `README.md`)
- Part Mappings → Part Database: looks up parts (evidence: `packages/part-mapper/src/mappings.ts`)
- Workbench → DigiKey Search: requests search (evidence: `apps/web/src/App.tsx`)
- Integration Adapters → Part Database: uses part data (evidence: `packages/integrations/src/index.ts`)
- Circuit Exporters → Verilog Export: exports HDL (evidence: `packages/exporters/src/index.ts`)
- Circuit Exporters → Ligic JSON Export: exports JSON (evidence: `packages/exporters/src/index.ts`)
- Circuit Exporters → KiCad Export Stub: offers placeholder (evidence: `packages/exporters/src/index.ts`)
- Simulation Engine → Circuit Data Model: evaluates circuit (evidence: `README.md`)
- Verilog Export → Circuit Data Model: reads circuit data (evidence: `packages/exporters/src/verilog.ts`)
- Truth Table Import → Circuit Data Model: builds circuit data (evidence: `apps/web/src/lib/truthTableImport.ts`)
- Part Mappings → Circuit Data Model: defines mappings (evidence: `README.md`)