ZapTrace Architecture¶
Overview¶
ZapTrace is designed as a layered EDA kernel with a deterministic core, AI-assisted workflows, and multiple interface surfaces.
┌─────────────────────────────────────────────────────────────┐
│ Interfaces │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────────┐ │
│ │ CLI │ │ MCP Server│ │REST API │ │ Python SDK │ │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ └──────┬─────┘ │
├───────┴──────────────┴────────────┴────────────────┴───────┤
│ Agent Layer │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ Tool Registry (87 agent-facing tools) │ │
│ │ Pipeline Autopilot │ │
│ └──────────────────────────────────────────────────────┘ │
├────────────────────────────────────────────────────────────┤
│ Core Layer │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────┐ │
│ │ Models │ │ Parser │ │ Diff │ │ Exceptions │ │
│ │(Pydantic)│ │ (YAML) │ │ Engine │ │ (framework) │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────────┘ │
├────────────────────────────────────────────────────────────┤
│ Domain Layer │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────┐ │
│ │EE Knowl- │ │ Classi- │ │Footprint │ │ Constraints │ │
│ │edge Base │ │ fier │ │Engine │ │ & Presets │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────────┘ │
├────────────────────────────────────────────────────────────┤
│ Verification Layer │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────┐ │
│ │ERC Engine│ │DRC Engine│ │ Patches │ │ Rules │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────────┘ │
├────────────────────────────────────────────────────────────┤
│ Algorithm Layer │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────┐ │
│ │ Placer │ │ Router │ │GridRoute │ │ Copper Pour │ │
│ │(grid+fd) │ │(Manhattan│ │ r │ │(flood-fill) │ │
│ │ │ │ MST) │ │ │ │ │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────────┘ │
├────────────────────────────────────────────────────────────┤
│ Export Layer │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────┐ │
│ │ Gerber │ │ Excellon │ │ BOM │ │ KiCad │ │
│ │(RS-274X) │ │ (Drill) │ │(CSV/JSON)│ │ (Schematic) │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────────┘ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────┐ │
│ │ SVG │ │ Pick │ │Manufact. │ │ Proof Pack │ │
│ │Schematic │ │ & Place │ │ Bundle │ │ (ZIP+meta) │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────────┘ │
├────────────────────────────────────────────────────────────┤
│ Extension Layer │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────┐ │
│ │ Synthesis│ │ Library │ │ Plugin │ │ Rust Core │ │
│ │(template)│ │ Loader │ │ Manager │ │ (optional) │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────────┘ │
└────────────────────────────────────────────────────────────┘
Package Structure¶
zaptrace/ # Main Python package
├── __init__.py # Package metadata
├── core/ # Design models, parser, exceptions
│ ├── models.py # Pydantic models (Design, Component, Net, etc.)
│ ├── parser.py # YAML design file parser
│ ├── diff.py # Design comparison engine
│ └── exceptions.py # Domain exceptions
├── ee/ # Electrical engineering knowledge
│ ├── classifier.py # Net classification (power, signal, analog, etc.)
│ ├── footprints.py # Parametric footprint generation
│ ├── knowledge.py # EE knowledge base (trace widths, clearances)
│ ├── schematic/ # Schematic rendering engine
│ ├── drc/ # Design Rule Checking engine
│ ├── constraints/ # Design constraint definitions
│ ├── routing/ # Route-specific EDA logic
│ └── presets/ # Manufacturing presets (JLCPCB, etc.)
├── erc/ # Electrical Rule Checking
│ ├── models.py # ERC result models
│ ├── rules.py # ERC rule implementations
│ ├── runner.py # ERC rule runner
│ └── patches.py # Auto-patch suggestions
├── algo/ # Placement and routing algorithms
│ ├── placer.py # Grid + force-directed placement
│ ├── router.py # Manhattan MST routing
│ ├── grid_router.py # Grid-based A* routing
│ ├── copper_pour.py # Flood-fill copper pours
│ ├── diff_pair.py # Differential pair routing
│ └── fillet.py # Trace fillet/rounding
├── export/ # Output generation
│ ├── gerber.py # Gerber RS-274X export
│ ├── excellon.py # Excellon drill export
│ ├── bom.py # BOM CSV/JSON generation
│ ├── manufacturing.py # Manufacturing bundle (ZIP)
│ ├── kicad.py # KiCad schema export
│ ├── svg.py # SVG rendering
│ └── report.py # Markdown report generation
├── synthesis/ # Design synthesis from intent
│ ├── engine.py # Template-based synthesis
│ └── templates/ # Design templates
├── pipeline/ # Design flow autopilot
│ └── autopilot.py # Multi-stage pipeline runner
├── mcp/ # MCP protocol server
│ └── server.py # FastMCP server (87 agent-facing tools)
├── api/ # REST API
│ ├── server.py # FastAPI server
│ ├── models.py # API request/response models
│ └── routes/ # API route definitions
├── cli/ # Command-line interface
│ ├── main.py # Click CLI (17+ commands)
│ └── output.py # Rich console output helpers
├── agent/ # Agent tool definitions
│ ├── _tool_impls.py # Tool implementations
│ └── tools.py # Tool registry
├── library/ # Component library
│ └── loader.py # Library file loader
├── proof/ # Proof pack system
│ ├── __init__.py
│ ├── manifest.py
│ └── pack.py
└── plugins/ # Plugin system
├── __init__.py
├── manifest.py
└── loader.py
zaptrace_core/ # Optional Rust extension
├── Cargo.toml
└── src/lib.rs
data/ # Component library data files
├── library/
│ ├── passive/ # Resistors, capacitors, inductors
│ ├── mcu/ # Microcontrollers
│ ├── connector/ # Connectors
│ ├── power/ # Power management
│ ├── sensor/ # Sensors
│ ├── rf/ # RF components
│ └── optoelectronic/# LEDs, displays, photodiodes
tests/ # Test suite (count enforced by CI)
examples/ # Example designs
docs/ # Documentation
Key Design Decisions¶
Why Pydantic?¶
All core models use Pydantic for validation, serialization, and schema generation. This gives us automatic JSON Schema output, type-safe construction, and clear error messages.
Why In-Memory Session State?¶
The current session-based design store (dict) is a simplification for CLI/MCP usage. In production, this would be replaced with a persistent store (SQLite, Redis, or file-based).
Why Algorithmic Routing (not ML)?¶
Deterministic, repeatable routing is essential for a verification-first tool. ML-assisted routing is a future addition, but the core must always produce reproducible results.
Why Multiple Export Formats?¶
Different users need different outputs: KiCad for GUI editing, Gerber for fabrication, SVG for documentation, BOM for procurement. Each export is independently generated from the same design model.
Why Proof Packs?¶
Trust is earned through transparency. Proof packs let anyone verify exactly what ZapTrace generated, why, and whether all checks passed. This is essential for an AI-native EDA tool claiming "with proofs."
Data Flow¶
- Input: YAML file or natural language intent
- Parse/Synthesize: Produces a validated
Designmodel - Classify: EE knowledge enriches nets with classifications
- ERC: Validates electrical connectivity and pin compatibility
- Place: Arranges components on the board
- Route: Connects component pins with traces
- DRC: Validates physical design against manufacturing rules
- Export: Generates fabrication artifacts
- Proof Pack: Bundles everything with reproducibility metadata