# rtimothyedwards/magic architecture

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

- Interactive diagram: https://gitdiagram.com/rtimothyedwards/magic
- Repository: https://github.com/rtimothyedwards/magic

## Overview

Magic is a large C-based VLSI layout system built around a shared in-memory layout database, with multiple front ends and many specialized analysis/format-conversion tools layered on top. The repo is not a single app so much as a suite of cooperating executables and libraries.

1. Core architectural center: the layout database
- The `database/`, `tiles/`, `bplane/`, `utils/`, and `select/` directories form the central model layer.
- The database stores cells, tiles, geometry, labels, connectivity, tech information, timestamps, and undo state.
- `tiles` provides the underlying tile/plane representation; `bplane` is an alternate cell-plane implementation used for efficiency on hierarchical cells.
- `utils` supplies shared infrastructure: geometry, hashing, lists, undo, path traversal, tech parsing, netlist helpers, and memory/util primitives.

2. Editor and interaction layer
- The interactive layout editor lives primarily in `magic/`, `commands/`, `textio/`, `windows/`, `graphics/`, `dbwind/`, `cmwind/`, `netmenu/`, `plot/`, and `wiring/`.
- `commands/` implements user commands and command dispatch.
- `textio/` handles terminal input, output, and command-line interaction.
- `windows/`, `graphics/`, `dbwind/`, and `cmwind/` manage display, view updates, feedback, colors, and window-specific behavior.
- `select/` manages selection semantics and undo/redo for selected geometry and nets.
- `wiring/` contains interactive wire-editing support.

3. Main data flow for editing
- User input arrives through the text console, Tk/Tcl bindings, or GUI events.
- Commands mutate the central database.
- The database notifies display layers (`dbwind`, `graphics`, `windows`) to redraw affected regions.
- Selection, undo, and feedback subsystems track user operations separately from raw geometry so edits can be reversed and visualized cleanly.

4. Technology-file and rule system
- `scmos/` and parts of `database/`, `utils/tech.*`, `drc/`, and `extract/` reflect Magic’s technology-driven architecture.
- Process rules, layer definitions, display styles, extraction rules, and CIF/GDS-related behavior are driven by technology files rather than hardcoded.
- This makes technology data a first-class input boundary: the same editor/extractor/router code adapts to different fabrication processes through tech configuration.

5. Geometry analysis and verification tools
- `drc/` performs design-rule checking.
- `extract/` computes connectivity and device extraction from layout.
- `resis/` performs more detailed resistance-related extraction and resistor network work.
- `sim/` bridges layout extraction into simulation-oriented data.
- These tools all consume the same layout database and tech information, but produce analysis results rather than editing the geometry itself.

6. Routing and layout modification subsystems
- Automatic and interactive routing are split across `router/`, `grouter/`, `garouter/`, `irouter/`, `mzrouter/`, `gcr/`, `plow/`, and `bplane/`.
- Different routers target different use cases: detailed routing, maze routing, global routing, interactive routing, channel routing, and channel compaction/plowing.
- These modules read pins, layers, constraints, and connectivity from the database, then write routed geometry back into it.

7. Import/export and interchange formats
- File-format adapters are a major boundary in the repo: `calma/` for GDS/Calma, `cif/` for CIF, `lef/` for LEF/DEF, `ext2sim/`, `ext2spice/`, `extcheck/`, `net2ir/`, and `extflat/`.
- These modules translate between Magic’s internal database and external EDA interchange formats.
- The flow is generally: external file → parser/reader → internal database or netlist/extract structures; and the reverse for writers/exporters.
- This is one of the most important architectural separations in the repo.

8. Scripting and extensibility
- `tcltk/` integrates Tcl/Tk for scripting and GUI composition.
- `lisp/` adds a Scheme/Lisp-style extension environment, historically used for scripted commands and layout automation.
- `npm/` exposes JavaScript/Tcl wrappers and examples, including wasm-oriented integration.
- These layers are not the core engine; they are extension surfaces that call into the same command and database APIs.

9. Rendering backends and platform abstraction
- `graphics/` contains multiple rendering implementations and backends: X11, Tk, OpenGL, Cairo, and null/headless variants.
- The repo is designed to run with different display technologies without changing the database or command logic.
- `magic/magicWasm.c` and the `toolchains/emscripten/` directory show a WebAssembly build path.
- This is a clear boundary: platform graphics are abstracted behind the graphics subsystem, while the editor/database remain backend-independent.

10. Command-line utilities and batch-mode workflows
- Several top-level subdirectories build standalone programs, not just library code.
- Examples include `extcheck`, `net2ir`, `plot`, `sim`, and the `magicdnull`/batch-mode pathways in `tcltk/`.
- These tools usually reuse the same lower-level libraries for parsing, database access, geometry, and tech handling, but operate without the full interactive GUI.

11. Build, packaging, and distribution
- `Makefile`, `rules.mak`, `configure`, and `scripts/` drive the cross-platform build.
- GitHub Actions under `.github/workflows/` produce CI builds for Linux, macOS, AArch64, WASM, and AppImage variants.
- `appimage/` contains containerized packaging recipes, and `toolchains/emscripten/` supports browser/WASM builds.
- These are deployment concerns rather than runtime architecture, but they matter because Magic is distributed as a family of native and packaged binaries.

12. Documentation and technology examples as part of the system model
- `doc/` is unusually extensive and functions as part of the product architecture: it documents commands, file formats, tech files, tutorials, and historical behavior.
- `scmos/examples/`, `doc/tutcells/`, and related assets provide canonical design inputs used to validate readers, routers, extractors, and tech-file semantics.
- For diagramming, these should be treated as fixtures and reference data flowing into the same core tools.

Overall, the cleanest architecture diagram is: front ends and format adapters feed a central layout database; analysis and routing tools read/write that database; graphics/windowing layers observe it for display; tech files configure behavior; and scripting/batch tools wrap the same core APIs through Tcl, Lisp, or headless entry points.

Main entry points: [`database/DBcell.c`](https://github.com/rtimothyedwards/magic/blob/master/database/DBcell.c) (Layout DB), [`extract/ExtMain.c`](https://github.com/rtimothyedwards/magic/blob/master/extract/ExtMain.c) (Extract), [`commands/CmdSubrs.c`](https://github.com/rtimothyedwards/magic/blob/master/commands/CmdSubrs.c) (Commands), [`magic/magicTop.c`](https://github.com/rtimothyedwards/magic/blob/master/magic/magicTop.c) (Magic entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core model"]
  node_database[("Layout DB<br/>cell database<br/>[DBcell.c]")]
  node_tiles["Tiles<br/>tile planes<br/>[tile.c]"]
  node_bplane["B-plane<br/>cell planes<br/>[bpMain.c]"]
  node_utils["Core utils<br/>shared library<br/>[utils.h]"]
end

subgraph group_interactive["Interactive editor"]
  node_magic_top["Magic entry<br/>main editor<br/>[magicTop.c]"]
  node_textio["Text I/O<br/>console I/O<br/>[txMain.c]"]
  node_commands["Commands<br/>dispatch layer<br/>[CmdSubrs.c]"]
  node_select["Selection<br/>[selOps.c]"]
  node_dbwind["DB window<br/>view updates<br/>[DBWdisplay.c]"]
  node_windows["Windows<br/>window system<br/>[windMain.c]"]
  node_wiring["Wiring<br/>wire edit<br/>[wireOps.c]"]
end

subgraph group_analysis["Analysis and extraction"]
  node_drc["DRC<br/>verification<br/>[DRCmain.c]"]
  node_extract["Extract<br/>[ExtMain.c]"]
  node_resis["Resistive extract<br/>resistance analysis<br/>[ResMain.c]"]
  node_sim["Simulation bridge<br/>netlist bridge<br/>[SimExtract.c]"]
end

subgraph group_routing["Routing"]
  node_router["Router<br/>detailed routing<br/>[rtrMain.c]"]
  node_grouter["Global router<br/>global routing<br/>[grouteMain.c]"]
  node_mzrouter["Maze router<br/>maze routing<br/>[mzMain.c]"]
  node_plow["Plow<br/>compaction<br/>[PlowMain.c]"]
end

subgraph group_formats["Import/export"]
  node_calma["Calma/GDS<br/>gds io<br/>[CalmaRead.c]"]
  node_cif["CIF<br/>[CIFmain.c]"]
  node_lef["LEF/DEF<br/>[lefRead.c]"]
  node_ext2spice["Ext→Spice<br/>netlist export<br/>[ext2spice.c]"]
  node_extflat["Ext flat<br/>flattening<br/>[EFflat.c]"]
end

subgraph group_extensibility["Extensibility"]
  node_tcltk["Tcl/Tk<br/>script front end<br/>[tclmagic.c]"]
  node_lisp["Lisp/Scheme<br/>script engine<br/>[lispMain.c]"]
  node_npm["Node wrappers<br/>js bindings<br/>[index.js]"]
end

subgraph group_platform["Platform and build"]
  node_graphics["Graphics<br/>render backends<br/>[grMain.c]"]
  node_magic_wasm["WASM build<br/>web assembly<br/>[magicWasm.c]"]
  node_build["Build system<br/>build rules"]
  node_scmos["Tech data<br/>technology files<br/>[scmos.tech.in]"]
end

node_magic_top -->|"uses"| node_textio
node_magic_top -->|"dispatches"| node_commands
node_magic_top -->|"renders via"| node_graphics
node_commands -->|"mutates"| node_database
node_commands -->|"updates"| node_select
node_select -->|"tracks"| node_database
node_dbwind -->|"draws with"| node_graphics
node_windows -->|"hosts"| node_graphics
node_wiring -->|"writes"| node_database
node_database -->|"stores"| node_tiles
node_database -->|"uses"| node_bplane
node_database -->|"depends on"| node_utils
node_drc -->|"reads"| node_database
node_extract -->|"reads"| node_database
node_extract -->|"uses"| node_utils
node_resis -->|"extends"| node_extract
node_sim -->|"consumes"| node_extract
node_router -->|"writes"| node_database
node_grouter -->|"reads"| node_database
node_mzrouter -->|"reads"| node_database
node_plow -->|"modifies"| node_database
node_calma -->|"imports/exports"| node_database
node_cif -->|"imports/exports"| node_database
node_lef -->|"imports/exports"| node_database
node_ext2spice -->|"exports"| node_extract
node_extflat -->|"flattens"| node_database
node_tcltk -->|"wraps"| node_commands
node_lisp -->|"extends"| node_commands
node_npm -->|"binds"| node_tcltk
node_magic_wasm -->|"targets"| node_graphics
node_build -->|"builds"| node_magic_top
node_build -->|"packages"| node_tcltk
node_scmos -->|"configures"| node_drc
node_scmos -->|"configures"| node_extract
node_scmos -->|"drives"| node_calma

click node_magic_top "https://github.com/rtimothyedwards/magic/blob/master/magic/magicTop.c"
click node_textio "https://github.com/rtimothyedwards/magic/blob/master/textio/txMain.c"
click node_commands "https://github.com/rtimothyedwards/magic/blob/master/commands/CmdSubrs.c"
click node_select "https://github.com/rtimothyedwards/magic/blob/master/select/selOps.c"
click node_dbwind "https://github.com/rtimothyedwards/magic/blob/master/dbwind/DBWdisplay.c"
click node_graphics "https://github.com/rtimothyedwards/magic/blob/master/graphics/grMain.c"
click node_windows "https://github.com/rtimothyedwards/magic/blob/master/windows/windMain.c"
click node_wiring "https://github.com/rtimothyedwards/magic/blob/master/wiring/wireOps.c"
click node_database "https://github.com/rtimothyedwards/magic/blob/master/database/DBcell.c"
click node_tiles "https://github.com/rtimothyedwards/magic/blob/master/tiles/tile.c"
click node_bplane "https://github.com/rtimothyedwards/magic/blob/master/bplane/bpMain.c"
click node_utils "https://github.com/rtimothyedwards/magic/blob/master/utils/utils.h"
click node_drc "https://github.com/rtimothyedwards/magic/blob/master/drc/DRCmain.c"
click node_extract "https://github.com/rtimothyedwards/magic/blob/master/extract/ExtMain.c"
click node_resis "https://github.com/rtimothyedwards/magic/blob/master/resis/ResMain.c"
click node_sim "https://github.com/rtimothyedwards/magic/blob/master/sim/SimExtract.c"
click node_router "https://github.com/rtimothyedwards/magic/blob/master/router/rtrMain.c"
click node_grouter "https://github.com/rtimothyedwards/magic/blob/master/grouter/grouteMain.c"
click node_mzrouter "https://github.com/rtimothyedwards/magic/blob/master/mzrouter/mzMain.c"
click node_plow "https://github.com/rtimothyedwards/magic/blob/master/plow/PlowMain.c"
click node_calma "https://github.com/rtimothyedwards/magic/blob/master/calma/CalmaRead.c"
click node_cif "https://github.com/rtimothyedwards/magic/blob/master/cif/CIFmain.c"
click node_lef "https://github.com/rtimothyedwards/magic/blob/master/lef/lefRead.c"
click node_ext2spice "https://github.com/rtimothyedwards/magic/blob/master/ext2spice/ext2spice.c"
click node_extflat "https://github.com/rtimothyedwards/magic/blob/master/extflat/EFflat.c"
click node_tcltk "https://github.com/rtimothyedwards/magic/blob/master/tcltk/tclmagic.c"
click node_lisp "https://github.com/rtimothyedwards/magic/blob/master/lisp/lispMain.c"
click node_npm "https://github.com/rtimothyedwards/magic/blob/master/npm/index.js"
click node_magic_wasm "https://github.com/rtimothyedwards/magic/blob/master/magic/magicWasm.c"
click node_build "https://github.com/rtimothyedwards/magic/tree/master/Makefile"
click node_scmos "https://github.com/rtimothyedwards/magic/blob/master/scmos/scmos.tech.in"

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_database,node_tiles,node_bplane,node_utils,node_graphics,node_magic_wasm,node_build,node_scmos toneBlue
class node_magic_top,node_textio,node_commands,node_select,node_dbwind,node_windows,node_wiring toneAmber
class node_drc,node_extract,node_resis,node_sim toneMint
class node_router,node_grouter,node_mzrouter,node_plow toneRose
class node_calma,node_cif,node_lef,node_ext2spice,node_extflat toneIndigo
class node_tcltk,node_lisp,node_npm toneTeal
```

## Components

### Core model

Shared layout database and foundational geometry/data structures.

- [Layout DB](https://github.com/rtimothyedwards/magic/blob/master/database/DBcell.c): cell database · Central shared in-memory model for cells, geometry, labels, connectivity, tech, and undo. · `database/DBcell.c`
- [Tiles](https://github.com/rtimothyedwards/magic/blob/master/tiles/tile.c): tile planes · Underlying tile and plane representation for geometry storage. · `tiles/tile.c`
- [B-plane](https://github.com/rtimothyedwards/magic/blob/master/bplane/bpMain.c): cell planes · Alternate cell-plane implementation tuned for hierarchical efficiency. · `bplane/bpMain.c`
- [Core utils](https://github.com/rtimothyedwards/magic/blob/master/utils/utils.h): shared library · Common geometry, hashing, lists, paths, tech parsing, netlist, memory, and undo helpers. · `utils/utils.h`

### Interactive editor

User-facing command, selection, and display subsystems.

- [Magic entry](https://github.com/rtimothyedwards/magic/blob/master/magic/magicTop.c): main editor · Primary executable and startup path for the interactive editor. · `magic/magicTop.c`
- [Text I/O](https://github.com/rtimothyedwards/magic/blob/master/textio/txMain.c): console I/O · Terminal input, output, and command-line interaction. · `textio/txMain.c`
- [Commands](https://github.com/rtimothyedwards/magic/blob/master/commands/CmdSubrs.c): dispatch layer · Command parsing and editor command implementations. · `commands/CmdSubrs.c`
- [Selection](https://github.com/rtimothyedwards/magic/blob/master/select/selOps.c): selection state · Selection semantics plus undo/redo for selected geometry and nets. · `select/selOps.c`
- [DB window](https://github.com/rtimothyedwards/magic/blob/master/dbwind/DBWdisplay.c): view updates · Database-driven view updates, feedback, and highlighting. · `dbwind/DBWdisplay.c`
- [Windows](https://github.com/rtimothyedwards/magic/blob/master/windows/windMain.c): window system · Window management, event routing, and viewport behavior. · `windows/windMain.c`
- [Wiring](https://github.com/rtimothyedwards/magic/blob/master/wiring/wireOps.c): wire edit · Interactive wire editing support and related tech rules. · `wiring/wireOps.c`

### Analysis and extraction

Verification and extraction tools that consume the database.

- [DRC](https://github.com/rtimothyedwards/magic/blob/master/drc/DRCmain.c): verification · Design-rule checking over the layout database and tech rules. · `drc/DRCmain.c`
- [Extract](https://github.com/rtimothyedwards/magic/blob/master/extract/ExtMain.c): net extraction · Connectivity and device extraction from layout. · `extract/ExtMain.c`
- [Resistive extract](https://github.com/rtimothyedwards/magic/blob/master/resis/ResMain.c): resistance analysis · Detailed resistor-network and resistance extraction support. · `resis/ResMain.c`
- [Simulation bridge](https://github.com/rtimothyedwards/magic/blob/master/sim/SimExtract.c): netlist bridge · Bridges extracted layout data into simulation-oriented structures. · `sim/SimExtract.c`

### Routing

Automatic and interactive routing subsystems.

- [Router](https://github.com/rtimothyedwards/magic/blob/master/router/rtrMain.c): detailed routing · General routing engine for pins, vias, hazards, and route painting. · `router/rtrMain.c`
- [Global router](https://github.com/rtimothyedwards/magic/blob/master/grouter/grouteMain.c): global routing · Global routing and routing-net planning across the layout. · `grouter/grouteMain.c`
- [Maze router](https://github.com/rtimothyedwards/magic/blob/master/mzrouter/mzMain.c): maze routing · Maze-search-based routing and extension logic. · `mzrouter/mzMain.c`
- [Plow](https://github.com/rtimothyedwards/magic/blob/master/plow/PlowMain.c): compaction · Channel compaction and layout plowing tools. · `plow/PlowMain.c`

### Import/export

Interchange readers and writers around the internal database.

- [Calma/GDS](https://github.com/rtimothyedwards/magic/blob/master/calma/CalmaRead.c): gds io · Calma/GDS reader and writer. · `calma/CalmaRead.c`
- [CIF](https://github.com/rtimothyedwards/magic/blob/master/cif/CIFmain.c): cif io · CIF reader, writer, and tech handling. · `cif/CIFmain.c`
- [LEF/DEF](https://github.com/rtimothyedwards/magic/blob/master/lef/lefRead.c): lef/def io · LEF/DEF parsing and writing boundary. · `lef/lefRead.c`
- [Ext→Spice](https://github.com/rtimothyedwards/magic/blob/master/ext2spice/ext2spice.c): netlist export · Exports extracted connectivity into SPICE-oriented form. · `ext2spice/ext2spice.c`
- [Ext flat](https://github.com/rtimothyedwards/magic/blob/master/extflat/EFflat.c): flattening · Hierarchical flattening and flat extraction support. · `extflat/EFflat.c`

### Extensibility

Scripting and alternate front ends.

- [Tcl/Tk](https://github.com/rtimothyedwards/magic/blob/master/tcltk/tclmagic.c): script front end · Tcl/Tk integration for scripting, GUI composition, and wrappers. · `tcltk/tclmagic.c`
- [Lisp/Scheme](https://github.com/rtimothyedwards/magic/blob/master/lisp/lispMain.c): script engine · Embedded Scheme/Lisp extension environment for automation. · `lisp/lispMain.c`
- [Node wrappers](https://github.com/rtimothyedwards/magic/blob/master/npm/index.js): js bindings · JavaScript and Tcl wrapper layer, including wasm-oriented examples. · `npm/index.js`

### Platform and build

Backend rendering, WebAssembly, and build/distribution support.

- [Graphics](https://github.com/rtimothyedwards/magic/blob/master/graphics/grMain.c): render backends · Display abstraction with X11, Tk, OpenGL, Cairo, and null backends. · `graphics/grMain.c`
- [WASM build](https://github.com/rtimothyedwards/magic/blob/master/magic/magicWasm.c): web assembly · WebAssembly entry path for browser-style builds. · `magic/magicWasm.c`
- [Build system](https://github.com/rtimothyedwards/magic/tree/master/Makefile): build rules · Top-level make/configuration and packaging machinery. · `Makefile`
- [Tech data](https://github.com/rtimothyedwards/magic/blob/master/scmos/scmos.tech.in): technology files · Process technology, layer, display, and example rule data. · `scmos/scmos.tech.in`

## Connections

- Magic entry → Text I/O: uses · Interactive startup and console command path.
- Magic entry → Commands: dispatches · User actions are translated into editor commands.
- Magic entry → Graphics: renders via · Editor output is drawn through backend-agnostic graphics.
- Commands → Layout DB: mutates · Commands edit the central layout database.
- Commands → Selection: updates · Commands operate on selection state and undo.
- Selection → Layout DB: tracks · Selection references geometry and nets in the database.
- DB window → Graphics: draws with · Database change notifications drive redraws.
- Windows → Graphics: hosts · Windowing sits above the rendering backends.
- Wiring → Layout DB: writes · Interactive wire editing commits routed geometry.
- Layout DB → Tiles: stores · Geometry is backed by tile and plane structures.
- Layout DB → B-plane: uses · Hierarchical cells may use alternate plane storage.
- Layout DB → Core utils: depends on · Core data structures rely on shared utilities.
- DRC → Layout DB: reads · Verification consumes the shared layout model.
- Extract → Layout DB: reads · Extraction traverses layout, labels, and connectivity.
- Extract → Core utils: uses · Extraction reuses tech and geometry helpers.
- Resistive extract → Extract: extends · Resistance analysis builds on extracted connectivity.
- Simulation bridge → Extract: consumes · Simulation bridging starts from extracted nets.
- Router → Layout DB: writes · Routing adds geometry back into the database.
- Global router → Layout DB: reads · Global routing consumes pins, layers, and constraints.
- Maze router → Layout DB: reads · Maze routing searches across the shared database.
- Plow → Layout DB: modifies · Compaction/plowing rewrites layout geometry.
- Calma/GDS → Layout DB: imports/exports · GDS/Calma translation is a boundary around the database.
- CIF → Layout DB: imports/exports · CIF translation maps between files and internal layout.
- LEF/DEF → Layout DB: imports/exports · LEF/DEF adapters translate to and from internal data.
- Ext→Spice → Extract: exports · SPICE output is driven by extracted connectivity.
- Ext flat → Layout DB: flattens · Flat translation and hierarchy expansion operate on layout data.
- Tcl/Tk → Commands: wraps · Tcl/Tk surfaces invoke the same command APIs.
- Lisp/Scheme → Commands: extends · Scheme/Lisp scripts call into Magic command interfaces.
- Node wrappers → Tcl/Tk: binds · Node examples and wrappers bridge into Tcl/Tk and Magic.
- WASM build → Graphics: targets · WASM build path shares the same editor/graphics split.
- Build system → Magic entry: builds · Top-level build rules produce the main executable.
- Build system → Tcl/Tk: packages · Build scripts assemble scripting and wrapper binaries.
- Tech data → DRC: configures · Technology files provide DRC rules and layer definitions.
- Tech data → Extract: configures · Extraction rules and tech data are technology-driven.
- Tech data → Calma/GDS: drives · Tech data influences interchange and display semantics.