# wulffern/cicpy architecture

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

- Interactive diagram: https://gitdiagram.com/wulffern/cicpy
- Repository: https://github.com/wulffern/cicpy

## Overview

cicpy is a Python toolbox for compiling ciccreator object definitions and translating `.cic` IC designs into other design formats. The main workflow is command-line input → design loading/compilation → layout and routing operations as needed → format-specific output. Separate capabilities include route analysis, a Qt design viewer, and an MCP server. The graph preserves README-documented commands; several implementation links are omitted because their source was not sampled.

Main entry points: [`src/cicpy/cic.py`](https://github.com/wulffern/cicpy/blob/master/src/cicpy/cic.py) (CLI commands), [`src/cicpy/core/layoutcell.py`](https://github.com/wulffern/cicpy/blob/master/src/cicpy/core/layoutcell.py) (Layout cells), [`src/cicpy/core/mazerouter.py`](https://github.com/wulffern/cicpy/blob/master/src/cicpy/core/mazerouter.py) (Maze routing), [`src/cicpy/compiler/builder.py`](https://github.com/wulffern/cicpy/blob/master/src/cicpy/compiler/builder.py) (Object compiler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry points"]
  node_cli["CLI commands<br/>[cic.py]"]
  node_compiler["Object compiler<br/>[builder.py]"]
  node_dispatch["Compile dispatch<br/>[dispatch.py]"]
  node_registry["Cell registry<br/>[registry.py]"]
end

subgraph group_design["Design model"]
  node_designmodel["Cell design model<br/>[cell.py]"]
  node_cellgroups["Cell groups<br/>[cellgroup.py]"]
  node_layout["Layout cells<br/>[layoutcell.py]"]
  node_technology["Technology rules<br/>[rules.py]"]
  node_rect["Geometry primitives<br/>[rect.py]"]
end

subgraph group_routing["Layout and routing"]
  node_maze["Maze routing<br/>[mazerouter.py]"]
  node_routes["Route geometry<br/>[route.py]"]
  node_tracks["Track analysis<br/>[trackmap.py]"]
  node_cuts["Via cuts<br/>[cut.py]"]
end

subgraph group_outputs["Format outputs"]
  node_printers["Format printers"]
  node_designprinter["Printer base<br/>[designprinter.py]"]
  node_magic["Magic integration<br/>[magic.py]"]
  node_xschem["Xschem integration<br/>[xschem.py]"]
end

subgraph group_interfaces["User interfaces"]
  node_gui["Qt viewer<br/>[mainwindow.py]"]
  node_guiapp["GUI launcher<br/>[app.py]"]
  node_mcp["MCP server<br/>[mcp_server.py]"]
end

node_engineer(("IC designer"))

node_engineer -->|"runs commands"| node_cli
node_engineer -->|"opens viewer"| node_guiapp
node_cli -->|"compiles definitions"| node_compiler
node_compiler -->|"uses dispatch"| node_dispatch
node_compiler -->|"registers cells"| node_registry
node_cli -->|"loads &#96;.cic&#96;"| node_designmodel
node_cli -->|"transpiles to formats"| node_printers
node_printers -->|"shares printer base"| node_designprinter
node_cli -->|"places and routes"| node_magic
node_cli -->|"netlists schematic"| node_xschem
node_cli -->|"searches routes"| node_maze
node_cli -->|"reports track use"| node_tracks
node_cli -->|"reports stack order"| node_cuts
node_cellgroups -->|"groups cells"| node_designmodel
node_cellgroups -->|"uses layout cells"| node_layout
node_layout -->|"uses cells"| node_designmodel
node_layout -->|"uses geometry"| node_rect
node_layout -->|"queries rules"| node_technology
node_maze -->|"searches track grid"| node_tracks
node_maze -->|"plans routes"| node_routes
node_maze -->|"accounts for cuts"| node_cuts
node_guiapp -->|"launches window"| node_gui
node_mcp -->|"invokes operations"| node_cli

click node_cli "https://github.com/wulffern/cicpy/blob/master/src/cicpy/cic.py"
click node_compiler "https://github.com/wulffern/cicpy/blob/master/src/cicpy/compiler/builder.py"
click node_dispatch "https://github.com/wulffern/cicpy/blob/master/src/cicpy/compiler/dispatch.py"
click node_registry "https://github.com/wulffern/cicpy/blob/master/src/cicpy/compiler/registry.py"
click node_designmodel "https://github.com/wulffern/cicpy/blob/master/src/cicpy/core/cell.py"
click node_cellgroups "https://github.com/wulffern/cicpy/blob/master/src/cicpy/core/cellgroup.py"
click node_layout "https://github.com/wulffern/cicpy/blob/master/src/cicpy/core/layoutcell.py"
click node_technology "https://github.com/wulffern/cicpy/blob/master/src/cicpy/core/rules.py"
click node_rect "https://github.com/wulffern/cicpy/blob/master/src/cicpy/core/rect.py"
click node_maze "https://github.com/wulffern/cicpy/blob/master/src/cicpy/core/mazerouter.py"
click node_routes "https://github.com/wulffern/cicpy/blob/master/src/cicpy/core/route.py"
click node_tracks "https://github.com/wulffern/cicpy/blob/master/src/cicpy/core/trackmap.py"
click node_cuts "https://github.com/wulffern/cicpy/blob/master/src/cicpy/core/cut.py"
click node_printers "https://github.com/wulffern/cicpy/tree/master/src/cicpy/printer"
click node_designprinter "https://github.com/wulffern/cicpy/blob/master/src/cicpy/printer/designprinter.py"
click node_magic "https://github.com/wulffern/cicpy/blob/master/src/cicpy/eda/magic.py"
click node_xschem "https://github.com/wulffern/cicpy/blob/master/src/cicpy/eda/xschem.py"
click node_gui "https://github.com/wulffern/cicpy/blob/master/src/cicpy/gui/mainwindow.py"
click node_guiapp "https://github.com/wulffern/cicpy/blob/master/src/cicpy/gui/app.py"
click node_mcp "https://github.com/wulffern/cicpy/blob/master/src/cicpy/mcp_server.py"

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_cli,node_compiler,node_dispatch,node_registry toneBlue
class node_designmodel,node_cellgroups,node_layout,node_technology,node_rect toneAmber
class node_maze,node_routes,node_tracks,node_cuts toneMint
class node_printers,node_designprinter,node_magic,node_xschem toneRose
class node_gui,node_guiapp,node_mcp,node_engineer toneIndigo
```

## Components

### Entry points

- [CLI commands](https://github.com/wulffern/cicpy/blob/master/src/cicpy/cic.py): `src/cicpy/cic.py`
- [Object compiler](https://github.com/wulffern/cicpy/blob/master/src/cicpy/compiler/builder.py): `src/cicpy/compiler/builder.py`
- [Compile dispatch](https://github.com/wulffern/cicpy/blob/master/src/cicpy/compiler/dispatch.py): `src/cicpy/compiler/dispatch.py`
- [Cell registry](https://github.com/wulffern/cicpy/blob/master/src/cicpy/compiler/registry.py): `src/cicpy/compiler/registry.py`

### Design model

- [Cell design model](https://github.com/wulffern/cicpy/blob/master/src/cicpy/core/cell.py): `src/cicpy/core/cell.py`
- [Cell groups](https://github.com/wulffern/cicpy/blob/master/src/cicpy/core/cellgroup.py): `src/cicpy/core/cellgroup.py`
- [Layout cells](https://github.com/wulffern/cicpy/blob/master/src/cicpy/core/layoutcell.py): `src/cicpy/core/layoutcell.py`
- [Technology rules](https://github.com/wulffern/cicpy/blob/master/src/cicpy/core/rules.py): `src/cicpy/core/rules.py`
- [Geometry primitives](https://github.com/wulffern/cicpy/blob/master/src/cicpy/core/rect.py): `src/cicpy/core/rect.py`

### Layout and routing

- [Maze routing](https://github.com/wulffern/cicpy/blob/master/src/cicpy/core/mazerouter.py): `src/cicpy/core/mazerouter.py`
- [Route geometry](https://github.com/wulffern/cicpy/blob/master/src/cicpy/core/route.py): `src/cicpy/core/route.py`
- [Track analysis](https://github.com/wulffern/cicpy/blob/master/src/cicpy/core/trackmap.py): `src/cicpy/core/trackmap.py`
- [Via cuts](https://github.com/wulffern/cicpy/blob/master/src/cicpy/core/cut.py): `src/cicpy/core/cut.py`

### Format outputs

- [Format printers](https://github.com/wulffern/cicpy/tree/master/src/cicpy/printer): `src/cicpy/printer`
- [Printer base](https://github.com/wulffern/cicpy/blob/master/src/cicpy/printer/designprinter.py): `src/cicpy/printer/designprinter.py`
- [Magic integration](https://github.com/wulffern/cicpy/blob/master/src/cicpy/eda/magic.py): `src/cicpy/eda/magic.py`
- [Xschem integration](https://github.com/wulffern/cicpy/blob/master/src/cicpy/eda/xschem.py): `src/cicpy/eda/xschem.py`

### User interfaces

- [Qt viewer](https://github.com/wulffern/cicpy/blob/master/src/cicpy/gui/mainwindow.py): `src/cicpy/gui/mainwindow.py`
- [GUI launcher](https://github.com/wulffern/cicpy/blob/master/src/cicpy/gui/app.py): `src/cicpy/gui/app.py`
- [MCP server](https://github.com/wulffern/cicpy/blob/master/src/cicpy/mcp_server.py): `src/cicpy/mcp_server.py`

### Other components

- **IC designer**

## Connections

- IC designer → CLI commands: runs commands (evidence: `README.md`)
- IC designer → GUI launcher: opens viewer (evidence: `README.md`)
- CLI commands → Object compiler: compiles definitions (evidence: `README.md`)
- Object compiler → Compile dispatch: uses dispatch (evidence: `src/cicpy/compiler/builder.py`)
- Object compiler → Cell registry: registers cells (evidence: `src/cicpy/compiler/builder.py`)
- CLI commands → Cell design model: loads `.cic` (evidence: `README.md`)
- CLI commands → Format printers: transpiles to formats (evidence: `README.md`)
- Format printers → Printer base: shares printer base (evidence: `src/cicpy/printer/skillschprinter.py`)
- CLI commands → Magic integration: places and routes (evidence: `README.md`)
- CLI commands → Xschem integration: netlists schematic (evidence: `README.md`)
- CLI commands → Maze routing: searches routes (evidence: `src/cicpy/cic.py`)
- CLI commands → Track analysis: reports track use (evidence: `README.md`)
- CLI commands → Via cuts: reports stack order (evidence: `README.md`)
- Cell groups → Cell design model: groups cells (evidence: `src/cicpy/core/cellgroup.py`)
- Cell groups → Layout cells: uses layout cells (evidence: `src/cicpy/core/cellgroup.py`)
- Layout cells → Cell design model: uses cells (evidence: `src/cicpy/core/layoutcell.py`)
- Layout cells → Geometry primitives: uses geometry (evidence: `src/cicpy/core/layoutcell.py`)
- Layout cells → Technology rules: queries rules (evidence: `src/cicpy/core/layoutcell.py`)
- Maze routing → Track analysis: searches track grid (evidence: `src/cicpy/core/mazerouter.py`)
- Maze routing → Route geometry: plans routes (evidence: `src/cicpy/core/mazerouter.py`)
- Maze routing → Via cuts: accounts for cuts (evidence: `src/cicpy/core/mazerouter.py`)
- GUI launcher → Qt viewer: launches window (evidence: `src/cicpy/gui/app.py`)
- MCP server → CLI commands: invokes operations (evidence: `src/cicpy/mcp_server.py`)
