Architecture

FalCAD is one engineering document model with several workbenches on top. A project is not five copies of a board. It is a linked graph with stable identities, explicit source-of-truth rules, versioned operations and validated derived artifacts.

┌──────────────────────────── falcad (app) ─────────────────────────────┐
│  React renderer (one code base for web + desktop)                     │
│  shell · command registry · workbench registry · inspector · panels   │
│  workbenches: schematic · simulation · PCB (2D/3D) · code/HDL · …     │
│  ProjectSession → StructuredDocument (transactions, undo, recovery)   │
│  PlatformAdapter: browser (FS Access / OPFS) | Electron bridge        │
└───────────────┬───────────────────────────────────────────────────────┘
                │ packages (TypeScript sources)
  ┌─────────────┼───────────────┬──────────────┬───────────┬──────────┐
  │ format      │ kernel        │ sim          │ pcb       │ hdl, mcu │
  │ .falcad,    │ netlist, ERC, │ MNA analog,  │ DRC,      │ Yosys/   │
  │ schemas,    │ transactions, │ logic, SPICE │ Gerber,   │ nextpnr  │
  │ migrations  │ templates,    │ export       │ Excellon, │ WASM,    │
  │             │ capabilities  │              │ 3D mesh   │ AVR emu  │
  └─────────────┴───────────────┴──────────────┴───────────┴──────────┘
        ▲ library (symbols, footprints)   ▲ toolchains (manifests, detection, safe execution)

  falcad-cli ── same engines, headless; local MCP server (read-only + proposals)
  falcad-sdk ── extension API; sandboxed extension host; signed packages
  falcad-cloud (private) ── ASP.NET Core, MongoDB, SignalR collaboration hub,
                            resource-based authorization, quotas, audit

Principles in code

• One definition per concept. Document schemas, ERC rules, DRC rules, commands, capability lists, the pin table and templates are each defined once. Other languages and docs consume generated artifacts that carry drift checks.
• Every design mutation is a transaction. It is validated against the schema and referential integrity and applied atomically. It drives undo/redo, crash recovery, collaboration and human review of automated proposals.
• Engines are pure. They don’t read the clock, the network or global state. Results carry provenance.
• No timers for correctness. Ordering comes from explicit events, server sequence and promises. The only timers are process deadlines and frame-coalesced rendering.
• Untrusted inputs everywhere. Projects, archives, HDL, tool output, extensions and MCP clients are all bounded, validated and confined.
• Honest capabilities. Every feature has a status backed by tests. The app’s Capabilities view and this site’s matrix are generated from the same registries.

Execution modes

A task (simulate, synthesize, compile, export) runs in one of these modes:

• browser-wasm — in the page or a worker
• local-native — a detected native tool, run through the hardened runner
• cloud-managed — only when the user chooses it, with a visible cost
• remote-approved-device — only with live local approval
• unsupported — reported, never faked

Code and designs are never uploaded just to run a task.

See the decision records for the reasoning behind each choice.