# the-openroad-project/opendb architecture

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

- Interactive diagram: https://gitdiagram.com/the-openroad-project/opendb
- Repository: https://github.com/the-openroad-project/opendb

## Overview

1. **What this repo is**
   OpenDB is a C++98 physical-design database library for chip layout data. It is not an application with one monolithic runtime; it is a reusable core library plus parsers, writers, language bindings, and tests.

2. **Main architectural boundary: public API vs internal implementation**
   The public surface is in `include/opendb`, especially `db.h`, `dbTypes.h`, and related headers. The implementation lives mainly in `src/db`, where each public object such as `dbInst` or `dbNet` has a corresponding private storage class and table-backed representation.

3. **Core data model**
   The central runtime objects are `dbDatabase`, `dbChip`, `dbBlock`, `dbTech`, and `dbLib`. These model the chip, its top-level design, technology rules, and standard-cell libraries. All objects carry persistent object IDs, so references survive save/restore cycles.

4. **Storage and object layout**
   Internal objects are stored in paged tables rather than as individually allocated nodes. That design choice affects the whole architecture: iteration is table-based, IDs are table indices, and the database favors compact, persistent in-memory state over pointer-rich graph structures.

5. **Primary input flow: LEF and DEF ingestion**
   The repo has dedicated readers for LEF and DEF in `src/lefin` and `src/defin`, backed by parser implementations in `src/lef` and `src/def`. LEF is used to build technology and library data; DEF is used to populate a design block, instances, nets, placements, routes, and physical constraints.

6. **Primary output flow: LEF and DEF generation**
   The inverse path is handled by `src/lefout` and `src/defout`, which serialize the database back to the text formats. This round-trip capability is a major architectural feature: parse, edit in memory, and emit again with minimal loss of structure.

7. **Binary persistence and exact restore**
   OpenDB also supports a binary save/restore path, called out in the README as faster than text LEF/DEF. This is important architecturally because the database is designed to be checkpointable and restorable with stable object IDs, enabling exact diffs and reproducible state recovery.

8. **Routing and connectivity subsystem**
   Net routing is represented with specialized structures such as `dbWire`, `dbWireCodec`, `dbWireGraph`, `dbRtTree`, `dbRtNode`, and `dbRtEdge`. This subsystem encodes DEF-style routed geometry as a compact wire representation rather than as a general-purpose graph store.

9. **Geometry and physical-shape subsystem**
   Layout primitives such as boxes, polygons, shapes, transforms, vias, layers, grids, rows, and track grids are spread across many `db*` classes. This is the physical geometry boundary of the database: it stores coordinates and topology, but not higher-level tool-specific spatial indexes.

10. **Technology and rule modeling**
   `dbTech`, `dbTechLayer`, `dbTechVia`, spacing/min-cut/antenna/same-net rules, and non-default rules model manufacturing constraints and technology metadata. This is where LEF technology semantics become database objects consumed by downstream tools.

11. **Language bindings and tool integration**
   `src/swig/python` and `src/swig/tcl` generate Python and Tcl bindings over the same C++ database API. These bindings are thin integration layers; they do not introduce a separate model, they expose the same underlying database objects to scripts and EDA tool flows.

12. **Code generation and schema-driven internals**
   `src/codeGenerator` indicates that part of the private implementation is generated from a schema (`schema.json`) rather than hand-written entirely. That means some of the database class boilerplate and implementation structure is mechanically produced, reinforcing the split between stable public API and generated/private internals.

13. **Validation, regression, and diffing**
   The repository includes C++ unit tests, Python tests, Tcl tests, and format regression data under `tests/`. There are also diff utilities in the LEF/DEF tooling and `dbDiff`, which support the “exact state” philosophy of the database.

14. **Build and delivery environment**
   The project is built with CMake, with CI and packaging scripts for Jenkins and Docker. Those are infrastructure concerns around the library, not core runtime components, but they matter because the repo is intended to be built into native tools and language bindings.

15. **How to draw the architecture**
   A good diagram should center on `dbDatabase` as the hub, with inbound arrows from LEF/DEF readers, outbound arrows to LEF/DEF writers and binary persistence, and side arrows to Tcl/Python bindings and test tooling. Around the hub, separate the technology/library model, block/layout model, and routing/wire model as the main internal subsystems.

Main entry points: [`src/db/dbBlock.h`](https://github.com/the-openroad-project/opendb/blob/master/src/db/dbBlock.h) (Block Model), [`CMakeLists.txt`](https://github.com/the-openroad-project/opendb/blob/master/CMakeLists.txt) (Build System), [`include/opendb/db.h`](https://github.com/the-openroad-project/opendb/blob/master/include/opendb/db.h) (DB API), [`src/db/dbDatabase.h`](https://github.com/the-openroad-project/opendb/blob/master/src/db/dbDatabase.h) (Database)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_api["Public API"]
  node_db_api["DB API<br/>public headers<br/>[db.h]"]
  node_db_types["DB Types<br/>public types<br/>[dbTypes.h]"]
end

subgraph group_grp_core["Core DB"]
  node_db_database[("Database<br/>core hub<br/>[dbDatabase.h]")]
  node_db_chip["Chip Model<br/>design root<br/>[dbChip.h]"]
  node_db_block["Block Model<br/>layout data<br/>[dbBlock.h]"]
  node_db_tech["Tech Model<br/>rules data<br/>[dbTech.h]"]
  node_db_lib["Lib Model<br/>cell library<br/>[dbLib.h]"]
  node_db_object{{"Object Tables<br/>table storage<br/>[dbObject.cpp]"}}
  node_db_geom(("Geometry<br/>physical shapes<br/>[dbShape.cpp]"))
  node_db_wire["Wire Model<br/>routing data<br/>[dbWire.h]"]
  node_db_rt["Route Tree<br/>routed topology<br/>[dbRtTree.cpp]"]
  node_binary_persist[("Binary Persist<br/>save/restore<br/>[dbStream.cpp]")]
  node_codegen{{"Codegen<br/>schema generator<br/>[schema.json]"}}
end

subgraph group_grp_io["Format IO"]
  node_lef_in["LEF In<br/>technology ingest<br/>[lefin.cpp]"]
  node_def_in["DEF In<br/>design ingest<br/>[defin.cpp]"]
  node_lef_out["LEF Out<br/>technology export<br/>[lefout.cpp]"]
  node_def_out["DEF Out<br/>design export<br/>[defout.cpp]"]
end

subgraph group_grp_bind["Bindings"]
  node_python_bind["Python<br/>swig binding<br/>[opendbpy.i]"]
  node_tcl_bind["Tcl<br/>swig binding<br/>[opendbtcl.i]"]
end

subgraph group_grp_test["Validation"]
  node_tests_cpp["C++ Tests<br/>unit/regression<br/>[test_wire.cpp]"]
  node_tests_py["Python Tests<br/>regression"]
  node_tests_tcl["Tcl Tests<br/>regression"]
end

subgraph group_grp_build["Build"]
  node_build["Build System<br/>cmake/ci<br/>[CMakeLists.txt]"]
end

node_db_api -->|"declares"| node_db_database
node_db_api -->|"shares types"| node_db_types
node_db_database -->|"owns"| node_db_chip
node_db_chip -->|"contains"| node_db_block
node_db_block -->|"references"| node_db_lib
node_db_block -->|"uses rules"| node_db_tech
node_db_database -->|"stores as tables"| node_db_object
node_db_object -->|"backs"| node_db_geom
node_db_block -->|"contains nets"| node_db_wire
node_db_wire -->|"encodes"| node_db_rt
node_db_tech -->|"defines layers"| node_db_geom
node_lef_in -->|"populates"| node_db_tech
node_lef_in -->|"populates"| node_db_lib
node_def_in -->|"populates"| node_db_block
node_def_in -->|"populates"| node_db_wire
node_lef_out -->|"reads"| node_db_tech
node_lef_out -->|"reads"| node_db_lib
node_def_out -->|"reads"| node_db_block
node_def_out -->|"reads"| node_db_wire
node_binary_persist -->|"checkpoints"| node_db_database
node_codegen -->|"generates"| node_db_object
node_python_bind -->|"wraps"| node_db_api
node_tcl_bind -->|"wraps"| node_db_api
node_tests_cpp -->|"verifies"| node_db_api
node_tests_py -->|"verifies"| node_python_bind
node_tests_tcl -->|"verifies"| node_tcl_bind
node_build -->|"builds"| node_lef_in
node_build -->|"builds"| node_def_in
node_build -->|"builds"| node_python_bind
node_build -->|"builds"| node_tcl_bind
node_build -->|"runs"| node_tests_cpp

click node_db_api "https://github.com/the-openroad-project/opendb/blob/master/include/opendb/db.h"
click node_db_types "https://github.com/the-openroad-project/opendb/blob/master/include/opendb/dbTypes.h"
click node_db_database "https://github.com/the-openroad-project/opendb/blob/master/src/db/dbDatabase.h"
click node_db_chip "https://github.com/the-openroad-project/opendb/blob/master/src/db/dbChip.h"
click node_db_block "https://github.com/the-openroad-project/opendb/blob/master/src/db/dbBlock.h"
click node_db_tech "https://github.com/the-openroad-project/opendb/blob/master/src/db/dbTech.h"
click node_db_lib "https://github.com/the-openroad-project/opendb/blob/master/src/db/dbLib.h"
click node_db_object "https://github.com/the-openroad-project/opendb/blob/master/src/db/dbObject.cpp"
click node_db_geom "https://github.com/the-openroad-project/opendb/blob/master/src/db/dbShape.cpp"
click node_db_wire "https://github.com/the-openroad-project/opendb/blob/master/src/db/dbWire.h"
click node_db_rt "https://github.com/the-openroad-project/opendb/blob/master/src/db/dbRtTree.cpp"
click node_binary_persist "https://github.com/the-openroad-project/opendb/blob/master/src/db/dbStream.cpp"
click node_codegen "https://github.com/the-openroad-project/opendb/blob/master/src/codeGenerator/schema.json"
click node_lef_in "https://github.com/the-openroad-project/opendb/blob/master/src/lefin/lefin.cpp"
click node_def_in "https://github.com/the-openroad-project/opendb/blob/master/src/defin/defin.cpp"
click node_lef_out "https://github.com/the-openroad-project/opendb/blob/master/src/lefout/lefout.cpp"
click node_def_out "https://github.com/the-openroad-project/opendb/blob/master/src/defout/defout.cpp"
click node_python_bind "https://github.com/the-openroad-project/opendb/blob/master/src/swig/python/opendbpy.i"
click node_tcl_bind "https://github.com/the-openroad-project/opendb/blob/master/src/swig/tcl/opendbtcl.i"
click node_tests_cpp "https://github.com/the-openroad-project/opendb/blob/master/src/db/test/test_wire.cpp"
click node_tests_py "https://github.com/the-openroad-project/opendb/blob/master/tests/python/05-read_def_test.py"
click node_tests_tcl "https://github.com/the-openroad-project/opendb/blob/master/tests/tcl/05-read_def_test.tcl"
click node_build "https://github.com/the-openroad-project/opendb/blob/master/CMakeLists.txt"

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_db_api,node_db_types toneBlue
class node_db_database,node_db_chip,node_db_block,node_db_tech,node_db_lib,node_db_object,node_db_geom,node_db_wire,node_db_rt,node_binary_persist,node_codegen toneAmber
class node_lef_in,node_def_in,node_lef_out,node_def_out toneMint
class node_python_bind,node_tcl_bind toneRose
class node_tests_cpp,node_tests_py,node_tests_tcl toneIndigo
class node_build toneTeal
```

## Components

### Public API

Stable C++ headers that define the library surface.

- [DB API](https://github.com/the-openroad-project/opendb/blob/master/include/opendb/db.h): public headers · Stable C++ entry points and object declarations for clients. · `include/opendb/db.h`
- [DB Types](https://github.com/the-openroad-project/opendb/blob/master/include/opendb/dbTypes.h): public types · Shared enums, IDs, and type definitions used across the API. · `include/opendb/dbTypes.h`

### Core DB

Persistent database objects, storage, and internal model.

- [Database](https://github.com/the-openroad-project/opendb/blob/master/src/db/dbDatabase.h): core hub · Top-level persistent database that anchors the object model. · `src/db/dbDatabase.h`
- [Chip Model](https://github.com/the-openroad-project/opendb/blob/master/src/db/dbChip.h): design root · Represents the chip and contains the top-level design block. · `src/db/dbChip.h`
- [Block Model](https://github.com/the-openroad-project/opendb/blob/master/src/db/dbBlock.h): layout data · Design block containing instances, nets, placement, and routing state. · `src/db/dbBlock.h`
- [Tech Model](https://github.com/the-openroad-project/opendb/blob/master/src/db/dbTech.h): rules data · Technology object holding layers, vias, and manufacturing rules. · `src/db/dbTech.h`
- [Lib Model](https://github.com/the-openroad-project/opendb/blob/master/src/db/dbLib.h): cell library · Standard-cell and macro library objects referenced by the design. · `src/db/dbLib.h`
- [Object Tables](https://github.com/the-openroad-project/opendb/blob/master/src/db/dbObject.cpp): table storage · Paged-table internals and object ID plumbing used by all db objects. · `src/db/dbObject.cpp`
- [Geometry](https://github.com/the-openroad-project/opendb/blob/master/src/db/dbShape.cpp): physical shapes · Boxes, shapes, transforms, vias, rows, grids, and related layout primitives. · `src/db/dbShape.cpp`
- [Wire Model](https://github.com/the-openroad-project/opendb/blob/master/src/db/dbWire.h): routing data · Compact routed-wire representation for nets and DEF geometry. · `src/db/dbWire.h`
- [Route Tree](https://github.com/the-openroad-project/opendb/blob/master/src/db/dbRtTree.cpp): routed topology · Route-tree codec and graph structures for routed connectivity. · `src/db/dbRtTree.cpp`
- [Binary Persist](https://github.com/the-openroad-project/opendb/blob/master/src/db/dbStream.cpp): save/restore · Binary checkpoint and restore path for fast exact state recovery. · `src/db/dbStream.cpp`
- [Codegen](https://github.com/the-openroad-project/opendb/blob/master/src/codeGenerator/schema.json): schema generator · Generates private implementation scaffolding from the schema. · `src/codeGenerator/schema.json`

### Format IO

LEF/DEF readers and writers around the database.

- [LEF In](https://github.com/the-openroad-project/opendb/blob/master/src/lefin/lefin.cpp): technology ingest · LEF reader path that populates technology and library data. · `src/lefin/lefin.cpp`
- [DEF In](https://github.com/the-openroad-project/opendb/blob/master/src/defin/defin.cpp): design ingest · DEF reader path that populates blocks, instances, nets, and routing. · `src/defin/defin.cpp`
- [LEF Out](https://github.com/the-openroad-project/opendb/blob/master/src/lefout/lefout.cpp): technology export · Serializes technology and library data back to LEF. · `src/lefout/lefout.cpp`
- [DEF Out](https://github.com/the-openroad-project/opendb/blob/master/src/defout/defout.cpp): design export · Serializes design state back to DEF. · `src/defout/defout.cpp`

### Bindings

Python and Tcl exposure over the same C++ API.

- [Python](https://github.com/the-openroad-project/opendb/blob/master/src/swig/python/opendbpy.i): swig binding · Python wrapper layer exposing the C++ database API. · `src/swig/python/opendbpy.i`
- [Tcl](https://github.com/the-openroad-project/opendb/blob/master/src/swig/tcl/opendbtcl.i): swig binding · Tcl wrapper layer exposing the C++ database API. · `src/swig/tcl/opendbtcl.i`

### Validation

Regression and unit coverage for core behavior and round-trips.

- [C++ Tests](https://github.com/the-openroad-project/opendb/blob/master/src/db/test/test_wire.cpp): unit/regression · Native tests covering core objects, geometry, callbacks, and wire logic. · `src/db/test/test_wire.cpp`
- [Python Tests](https://github.com/the-openroad-project/opendb/blob/master/tests/python/05-read_def_test.py): regression · Python integration tests for read/write and edit flows. · `tests/python/05-read_def_test.py`
- [Tcl Tests](https://github.com/the-openroad-project/opendb/blob/master/tests/tcl/05-read_def_test.tcl): regression · Tcl integration tests for read/write and database access. · `tests/tcl/05-read_def_test.tcl`

### Build

Project, CI, and packaging infrastructure.

- [Build System](https://github.com/the-openroad-project/opendb/blob/master/CMakeLists.txt): cmake/ci · CMake project plus CI and packaging scripts. · `CMakeLists.txt`

## Connections

- DB API → Database: declares · Public API exposes the database entry point.
- DB API → DB Types: shares types · Common enums and identifiers underpin the API.
- Database → Chip Model: owns · Database anchors the chip-level design model.
- Chip Model → Block Model: contains · Chip contains the top-level block/design.
- Block Model → Lib Model: references · Block objects refer to library masters and cells.
- Block Model → Tech Model: uses rules · Block state is constrained by technology definitions.
- Database → Object Tables: stores as tables · Persistent objects are table-backed and ID-addressed.
- Object Tables → Geometry: backs · Geometry primitives are represented by table-stored objects.
- Block Model → Wire Model: contains nets · Design connectivity is represented through wire objects.
- Wire Model → Route Tree: encodes · Route tree structures support compact routed connectivity.
- Tech Model → Geometry: defines layers · Technology rules are tied to geometric layers and vias.
- LEF In → Tech Model: populates · LEF ingestion builds technology objects and layer rules.
- LEF In → Lib Model: populates · LEF ingestion creates library and macro data.
- DEF In → Block Model: populates · DEF ingestion fills the design block with layout state.
- DEF In → Wire Model: populates · DEF ingestion reconstructs routed nets and wires.
- LEF Out → Tech Model: reads · LEF output serializes technology and library state.
- LEF Out → Lib Model: reads · LEF output emits macro/library information.
- DEF Out → Block Model: reads · DEF output serializes the design block state.
- DEF Out → Wire Model: reads · DEF output emits routed connectivity and geometry.
- Binary Persist → Database: checkpoints · Binary save/restore preserves the full database state.
- Codegen → Object Tables: generates · Schema-driven generation produces private implementation scaffolding.
- Python → DB API: wraps · Python exposes the same public C++ API.
- Tcl → DB API: wraps · Tcl exposes the same public C++ API.
- C++ Tests → DB API: verifies · C++ tests exercise core API and implementation behavior.
- Python Tests → Python: verifies · Python tests validate the binding and round-trip flows.
- Tcl Tests → Tcl: verifies · Tcl tests validate the binding and round-trip flows.
- Build System → LEF In: builds · Build system compiles the ingestion tooling.
- Build System → DEF In: builds · Build system compiles the ingestion tooling.
- Build System → Python: builds · Build system produces Python bindings.
- Build System → Tcl: builds · Build system produces Tcl bindings.
- Build System → C++ Tests: runs · CI and scripts execute native test suites.
