How we handle Altium files.
Our pipeline today, the altium_monkey reference, and the trade-offs.

How Circuit.ly parses Altium's undocumented binary files right now — set side by side with wavenumber-eng/altium_monkey, a deterministic toolkit that solved the same problem — plus the learnings worth carrying across every format we ingest, KiCad included.

We and altium_monkey reach the same core conclusion: own the format in deterministic code and keep the LLM out of the parse path. Where we diverge is what sits on top — Circuit.ly feeds a live collaborative editor; altium_monkey exposes a versioned JSON contract. This note maps both, honestly, with pros and cons.

The whole pipeline, end to end. An .SchDoc/.PcbDoc is an OLE2 compound file; a custom reader cracks it into streams; per-class parsers turn streams into a typed object model; from there one path round-trips back to byte-identical Altium, another projects a versioned JSON contract, a third renders enriched SVG. No LLM touches any of it. Our own pipeline mirrors this shape — an off-the-shelf container reader in place of the hand-rolled one, a collaborative model in place of the plain object model, and a live canvas in place of the static SVG export.

flowchart TD
  F["Altium file — OLE2 compound (.SchDoc / .PcbDoc)"]:::src
  OLE["AltiumOleFile — custom OLE reader/writer, zero deps"]:::alt
  subgraph PARSE["Per-class record parsers"]
    R1["Sch: length-prefixed param-string records"]:::alt
    R2["PCB: raw type-byte + subrecord streams"]:::alt
  end
  OM["Typed object model — ObjectCollection + records"]:::alt
  SER["Serializer — cp1252, font-id map, field presence"]:::alt
  RT["Byte-identical round-trip — unknown streams preserved"]:::con
  JSON["Versioned JSON contract — design.a1 / netlist.a0"]:::con
  SVG["Enriched SVG — data-* + embedded metadata"]:::con
  C["Consumers — CI checks, our UI, agents"]:::agent

  F --> OLE --> PARSE --> OM
  OM --> SER --> RT
  RT -.write.-> F
  OM --> JSON --> C
  OM --> SVG --> C

  classDef src fill:#94a3b822,stroke:#94a3b8,stroke-width:1.5px;
  classDef alt fill:#38bdf833,stroke:#38bdf8,stroke-width:1.5px;
  classDef con fill:#34d39933,stroke:#34d399,stroke-width:1.5px;
  classDef agent fill:#fb718533,stroke:#fb7185,stroke-width:2px;
      

Our Altium support is five native parsers, fully deterministic, no LLM, each with a matching serializer for round-trip. We didn't adopt altium_monkey; we built our own, tuned for a real-time collaborative editor rather than a one-shot importer.

Same problem — read an undocumented binary EDA format deterministically — solved two ways. We optimized for a live editor; altium_monkey optimized for a stable automation surface. Neither is wrong; they trade different things.

This is the one thing altium_monkey has that we don't. Our output is the live model + canvas render — perfect for editing, but there's no small, versioned, documented surface for CI, third-party exports, or agents to bind to. altium_monkey's design.a1 is the shape worth borrowing. We're already partway: our internal model is versioned; the move is to project a stable external contract on top of it.

{
  "schema": "altium_monkey.design.a1",   // the schema string IS the version
  "generator": "altium_monkey",
  "project": { "name": "bunny_brain", "parameters": {} },
  "components": [
    { "designator": "R1", "svg_id": "C12", "value": "10k",
      "footprint": "0402",
      "classification": { "prefix": "R", "type": "resistor", "pin_count": 2 } }
  ],
  "nets": [
    { "uid": "n7", "name": "GND", "auto_named": false,
      "terminals": [ { "designator": "R1", "pin": "2", "pin_type": "passive" } ] }
  ],
  "pnp": {
    "units": "mm", "position_mode": "altium-pick-place",
    "placements": [
      { "designator": "R1", "layer": "top",
        "center_x": 31.75, "center_y": 22.10, "rotation": 90 }
    ]
  }
}

<g data-component="U3" data-component-uid="…"
   data-layer-name="TOP">
  <path data-net="GND" data-net-class="power"
        data-primitive="track" />
</g>

Seven patterns worth carrying into Circuit.ly — ordered from highest leverage. Some we already do; a few (preserve-the-unknown, a stable contract) are the gaps from §04 worth closing. Each is tagged by scope: Altium-specific hard-won format detail, or All formats a discipline that holds for KiCad and anything we add next.