# saezlab/annnet architecture

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

- Interactive diagram: https://gitdiagram.com/saezlab/annnet
- Repository: https://github.com/saezlab/annnet

## Overview

1. **Top-level shape**
   annnet is a Python library organized around one central graph model in `annnet/core`, with three major extension surfaces around it: runtime graph-library adapters in `annnet/adapters`, file/storage I/O in `annnet/io`, and native algorithms in `annnet/algorithms`. Utilities, plotting, and backend-agnostic helpers live in `annnet/_support` and `annnet/utils`.

2. **Core domain model**
   The heart of the repo is the `Graph` object in `annnet/core/graph.py`. The core design is a sparse, incidence-matrix-based graph representation augmented with annotated tabular state. That means structure and metadata are intentionally separated: topology lives in matrix/record structures, while vertex/edge/layer/slice annotations are stored as dataframe-backed tables.

3. **State decomposition inside core**
   The core package is split into focused subsystems: `_Matrix` for structural incidence data, `_Layers` and `_Slices` for multilayer and slice semantics, `_Annotation` for metadata, `_History` for audit/undo-style state tracking, `_Views` for derived projections, `_Ops` for graph operations, and `_records` / `_common`-style helpers for internal record handling. This separation is a key architectural boundary: the graph object orchestrates these pieces rather than embedding everything in one class.

4. **Managers and views**
   Graph mutation is not just direct object editing; the model uses manager-like components and view objects to expose filtered or derived perspectives over the underlying state. The documentation and tests indicate that indexing, slice selection, active views, and derived caches are first-class concepts. For an architecture diagram, it is important to show that “views” sit on top of the core data rather than duplicating it.

5. **Backend accessors as a projection layer**
   `G.nx`, `G.ig`, and `G.gt` are graph-owned backend accessors under `annnet/core/backend_accessors`. They provide lazy projection of an AnnNet graph into NetworkX, igraph, or graph-tool graphs, and can also dispatch algorithms directly against those libraries. This is a distinct boundary: AnnNet remains the source of truth, while backend graphs are cached projections that must be refreshed after mutations.

6. **Explicit adapters for interoperability**
   The `annnet/adapters` package contains the conversion layer between AnnNet and external graph ecosystems, including NetworkX, igraph, graph-tool, and PyG. These adapters are used both by the backend accessors and by explicit import/export APIs. The repo keeps conversion logic separate from the core model so that interoperability does not leak third-party assumptions into the graph internals.

7. **File I/O and format modules**
   `annnet/io` is a family of format-specific readers/writers, not a single monolithic persistence layer. It includes GraphML, GEXF, SIF, SBML, CX2, JSON/NDJSON, CSV/TSV, Excel, Parquet, DataFrame exchange, and the native `.annnet` format. The I/O layer is where lossy-vs-lossless conversion policy lives, often via manifests that preserve information when a target format cannot encode all AnnNet semantics.

8. **Native persistence layout**
   The `.annnet` format is the repo’s lossless on-disk representation. The README and I/O modules show a split layout: `manifest.json` for metadata and versioning, Zarr for sparse structure, Parquet for tabular annotations and structural indices, and JSON for unstructured or auxiliary metadata. This makes storage a composition of technologies rather than a single database format.

9. **Algorithm layer**
   `annnet/algorithms` currently centers on traversal and similar graph-native routines. These algorithms are written against the AnnNet data model rather than against NetworkX or igraph, which keeps them usable even when no external backend is installed. In the diagram, this layer should point to core graph structures, not to adapters.

10. **Shared support layer**
    The `_support` package contains infrastructure that multiple subsystems reuse: dataframe backend abstraction, optional component handling, lazy exports, serialization helpers, plotting backend integration, metadata utilities, and graph-record helpers. This layer is what lets AnnNet stay backend-agnostic for tables while still supporting multiple optional ecosystems.

11. **Tabular backend strategy**
    AnnNet’s dataframe story is intentionally abstracted through Narwhals, with optional support for Polars, pandas, and PyArrow-backed objects. The architecture implication is that annotation tables are not tied to one dataframe implementation; instead, the core model depends on a compatibility layer that normalizes dataframe operations across engines.

12. **Optional runtime dependencies**
    The repo is designed so that the core runtime stays small: NumPy, SciPy, and Narwhals are the essential dependencies, while NetworkX, igraph, graph-tool, plotting libraries, and richer I/O dependencies are optional extras. That modular dependency boundary matters architecturally because it keeps the graph core usable in minimal environments and only activates extra subsystems when installed.

13. **Testing, docs, and validation as architectural guardrails**
    The test suite is broad and mirrors the subsystem boundaries: backend parity, IO round-trips, slice/history correctness, interoperability, and edge cases all have dedicated tests. Docs are also structured by architecture topics, which suggests the public API is intentionally aligned with the internal decomposition. For a diagram, this implies the repo is organized around preserving semantic consistency across conversions and storage, not just around feature modules.

14. **Primary data flow**
    The main flow is: user code mutates or queries `Graph` in core; views/managers derive projections; optional backend accessors convert to external graph objects for algorithms; IO modules serialize either to external interchange formats or to the native `.annnet` store; and manifests/caches preserve fidelity and speed across round-trips. The cleanest diagram should show core as the hub, with adapters and I/O as outward-facing projection/persistence layers.

Main entry points: [`annnet/core/graph.py`](https://github.com/saezlab/annnet/blob/main/annnet/core/graph.py) (Graph), [`annnet/_support/optional_components.py`](https://github.com/saezlab/annnet/blob/main/annnet/_support/optional_components.py) (Optional deps), [`annnet/core/backend_accessors/nx_accessor.py`](https://github.com/saezlab/annnet/blob/main/annnet/core/backend_accessors/nx_accessor.py) (NX Accessor), [`annnet/core/backend_accessors/ig_accessor.py`](https://github.com/saezlab/annnet/blob/main/annnet/core/backend_accessors/ig_accessor.py) (IG Accessor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core"]
  node_graph["Graph<br/>core model<br/>[graph.py]"]
  node_matrix["Matrix<br/>structure store<br/>[_Matrix.py]"]
  node_layers["Layers<br/>multilayer state<br/>[_Layers.py]"]
  node_slices["Slices<br/>slice state<br/>[_Slices.py]"]
  node_annotation["Annotations<br/>tabular metadata<br/>[_Annotation.py]"]
  node_history["History<br/>state tracking<br/>[_History.py]"]
  node_views["Views<br/>derived projections<br/>[_Views.py]"]
  node_ops["Ops<br/>[_Ops.py]"]
  node_records["Records<br/>[_records.py]"]
  node_nxacc["NX Accessor<br/>projection accessor<br/>[nx_accessor.py]"]
  node_igacc["IG Accessor<br/>projection accessor<br/>[ig_accessor.py]"]
  node_gtacc["GT Accessor<br/>projection accessor<br/>[gt_accessor.py]"]
end

subgraph group_adapters["Adapters"]
  node_nx["NetworkX<br/>adapter"]
  node_igraph["igraph<br/>adapter<br/>[igraph_adapter.py]"]
  node_graphtool["graph-tool<br/>adapter"]
  node_pyg["PyG<br/>adapter<br/>[pyg_adapter.py]"]
end

subgraph group_io["I/O"]
  node_annnetfmt[(".annnet<br/>native store<br/>[annnet_format.py]")]
  node_graphml["GraphML/GEXF<br/>exchange IO<br/>[graphml.py]"]
  node_jsonio["JSON<br/>exchange IO<br/>[json_format.py]"]
  node_parquet["Parquet<br/>tabular IO<br/>[parquet.py]"]
  node_csv["CSV/TSV<br/>tabular IO<br/>[csv_format.py]"]
  node_sbml["SBML<br/>domain IO<br/>[sbml.py]"]
  node_sif["SIF<br/>domain IO<br/>[sif.py]"]
end

subgraph group_support["Support"]
  node_dfbackend["Dataframes<br/>compat layer"]
  node_meta["Metadata<br/>utilities<br/>[metadata.py]"]
  node_optional["Optional deps<br/>utilities"]
  node_plotting["Plotting<br/>utilities<br/>[plotting.py]"]
end

subgraph group_algorithms["Algorithms"]
  node_traversal["Traversal<br/>algorithm<br/>[traversal.py]"]
end

node_graph -->|"stores topology"| node_matrix
node_graph -->|"tracks layers"| node_layers
node_graph -->|"tracks slices"| node_slices
node_graph -->|"stores metadata"| node_annotation
node_graph -->|"records changes"| node_history
node_graph -->|"exposes views"| node_views
node_graph -->|"mutates via"| node_ops
node_graph -->|"uses records"| node_records
node_graph -->|"projected by"| node_nxacc
node_graph -->|"projected by"| node_igacc
node_graph -->|"projected by"| node_gtacc
node_nxacc -->|"converts to"| node_nx
node_igacc -->|"converts to"| node_igraph
node_gtacc -->|"converts to"| node_graphtool
node_graph -->|"exports to"| node_pyg
node_graph -->|"persists as"| node_annnetfmt
node_graph -->|"imports/exports"| node_graphml
node_graph -->|"imports/exports"| node_jsonio
node_graph -->|"stores tables"| node_parquet
node_graph -->|"imports/exports"| node_csv
node_graph -->|"imports/exports"| node_sbml
node_graph -->|"imports/exports"| node_sif
node_dfbackend -->|"backing tables"| node_annotation
node_meta -->|"supports"| node_annnetfmt
node_optional -->|"gates"| node_nxacc
node_optional -->|"gates"| node_igacc
node_optional -->|"gates"| node_gtacc
node_optional -->|"gates"| node_plotting
node_plotting -->|"visualizes"| node_graph
node_traversal -->|"operates on"| node_graph
node_traversal -->|"uses projections"| node_views

click node_graph "https://github.com/saezlab/annnet/blob/main/annnet/core/graph.py"
click node_matrix "https://github.com/saezlab/annnet/blob/main/annnet/core/_Matrix.py"
click node_layers "https://github.com/saezlab/annnet/blob/main/annnet/core/_Layers.py"
click node_slices "https://github.com/saezlab/annnet/blob/main/annnet/core/_Slices.py"
click node_annotation "https://github.com/saezlab/annnet/blob/main/annnet/core/_Annotation.py"
click node_history "https://github.com/saezlab/annnet/blob/main/annnet/core/_History.py"
click node_views "https://github.com/saezlab/annnet/blob/main/annnet/core/_Views.py"
click node_ops "https://github.com/saezlab/annnet/blob/main/annnet/core/_Ops.py"
click node_records "https://github.com/saezlab/annnet/blob/main/annnet/core/_records.py"
click node_nxacc "https://github.com/saezlab/annnet/blob/main/annnet/core/backend_accessors/nx_accessor.py"
click node_igacc "https://github.com/saezlab/annnet/blob/main/annnet/core/backend_accessors/ig_accessor.py"
click node_gtacc "https://github.com/saezlab/annnet/blob/main/annnet/core/backend_accessors/gt_accessor.py"
click node_nx "https://github.com/saezlab/annnet/blob/main/annnet/adapters/networkx_adapter.py"
click node_igraph "https://github.com/saezlab/annnet/blob/main/annnet/adapters/igraph_adapter.py"
click node_graphtool "https://github.com/saezlab/annnet/blob/main/annnet/adapters/graphtool_adapter.py"
click node_pyg "https://github.com/saezlab/annnet/blob/main/annnet/adapters/pyg_adapter.py"
click node_annnetfmt "https://github.com/saezlab/annnet/blob/main/annnet/io/annnet_format.py"
click node_graphml "https://github.com/saezlab/annnet/blob/main/annnet/io/graphml.py"
click node_jsonio "https://github.com/saezlab/annnet/blob/main/annnet/io/json_format.py"
click node_parquet "https://github.com/saezlab/annnet/blob/main/annnet/io/parquet.py"
click node_csv "https://github.com/saezlab/annnet/blob/main/annnet/io/csv_format.py"
click node_sbml "https://github.com/saezlab/annnet/blob/main/annnet/io/sbml.py"
click node_sif "https://github.com/saezlab/annnet/blob/main/annnet/io/sif.py"
click node_dfbackend "https://github.com/saezlab/annnet/blob/main/annnet/_support/dataframe_backend.py"
click node_meta "https://github.com/saezlab/annnet/blob/main/annnet/_support/metadata.py"
click node_optional "https://github.com/saezlab/annnet/blob/main/annnet/_support/optional_components.py"
click node_plotting "https://github.com/saezlab/annnet/blob/main/annnet/utils/plotting.py"
click node_traversal "https://github.com/saezlab/annnet/blob/main/annnet/algorithms/traversal.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_graph,node_matrix,node_layers,node_slices,node_annotation,node_history,node_views,node_ops,node_records,node_nxacc,node_igacc,node_gtacc toneBlue
class node_nx,node_igraph,node_graphtool,node_pyg toneAmber
class node_annnetfmt,node_graphml,node_jsonio,node_parquet,node_csv,node_sbml,node_sif toneMint
class node_dfbackend,node_meta,node_optional,node_plotting toneRose
class node_traversal toneIndigo
```

## Components

### Core

Source-of-truth graph model and internal state subsystems

- [Graph](https://github.com/saezlab/annnet/blob/main/annnet/core/graph.py): core model · Central AnnNet graph object and orchestration boundary · `annnet/core/graph.py`
- [Matrix](https://github.com/saezlab/annnet/blob/main/annnet/core/_Matrix.py): structure store · Sparse incidence and structural state · `annnet/core/_Matrix.py`
- [Layers](https://github.com/saezlab/annnet/blob/main/annnet/core/_Layers.py): multilayer state · Layer semantics and layer-aware structure · `annnet/core/_Layers.py`
- [Slices](https://github.com/saezlab/annnet/blob/main/annnet/core/_Slices.py): slice state · Slice semantics and selection state · `annnet/core/_Slices.py`
- [Annotations](https://github.com/saezlab/annnet/blob/main/annnet/core/_Annotation.py): tabular metadata · Vertex, edge, layer, and slice annotation tables · `annnet/core/_Annotation.py`
- [History](https://github.com/saezlab/annnet/blob/main/annnet/core/_History.py): state tracking · Mutation history and audit-style tracking · `annnet/core/_History.py`
- [Views](https://github.com/saezlab/annnet/blob/main/annnet/core/_Views.py): derived projections · Filtered and derived graph views · `annnet/core/_Views.py`
- [Ops](https://github.com/saezlab/annnet/blob/main/annnet/core/_Ops.py): graph ops · Core graph operations and mutation helpers · `annnet/core/_Ops.py`
- [Records](https://github.com/saezlab/annnet/blob/main/annnet/core/_records.py): internal records · Internal record handling and common graph state helpers · `annnet/core/_records.py`
- [NX Accessor](https://github.com/saezlab/annnet/blob/main/annnet/core/backend_accessors/nx_accessor.py): projection accessor · Lazy NetworkX projection and backend dispatch · `annnet/core/backend_accessors/nx_accessor.py`
- [IG Accessor](https://github.com/saezlab/annnet/blob/main/annnet/core/backend_accessors/ig_accessor.py): projection accessor · Lazy igraph projection and backend dispatch · `annnet/core/backend_accessors/ig_accessor.py`
- [GT Accessor](https://github.com/saezlab/annnet/blob/main/annnet/core/backend_accessors/gt_accessor.py): projection accessor · Lazy graph-tool projection and backend dispatch · `annnet/core/backend_accessors/gt_accessor.py`

### Adapters

Projections to external graph ecosystems

- [NetworkX](https://github.com/saezlab/annnet/blob/main/annnet/adapters/networkx_adapter.py): adapter · Conversion layer for NetworkX interoperability · `annnet/adapters/networkx_adapter.py`
- [igraph](https://github.com/saezlab/annnet/blob/main/annnet/adapters/igraph_adapter.py): adapter · Conversion layer for igraph interoperability · `annnet/adapters/igraph_adapter.py`
- [graph-tool](https://github.com/saezlab/annnet/blob/main/annnet/adapters/graphtool_adapter.py): adapter · Conversion layer for graph-tool interoperability · `annnet/adapters/graphtool_adapter.py`
- [PyG](https://github.com/saezlab/annnet/blob/main/annnet/adapters/pyg_adapter.py): adapter · Conversion layer for PyTorch Geometric interoperability · `annnet/adapters/pyg_adapter.py`

### I/O

Import/export and native persistence formats

- [.annnet](https://github.com/saezlab/annnet/blob/main/annnet/io/annnet_format.py): native store · Lossless native persistence format with manifest and columnar storage · `annnet/io/annnet_format.py`
- [GraphML/GEXF](https://github.com/saezlab/annnet/blob/main/annnet/io/graphml.py): exchange IO · Graph interchange readers and writers · `annnet/io/graphml.py`
- [JSON](https://github.com/saezlab/annnet/blob/main/annnet/io/json_format.py): exchange IO · JSON and NDJSON serialization · `annnet/io/json_format.py`
- [Parquet](https://github.com/saezlab/annnet/blob/main/annnet/io/parquet.py): tabular IO · Columnar persistence for annotations and indices · `annnet/io/parquet.py`
- [CSV/TSV](https://github.com/saezlab/annnet/blob/main/annnet/io/csv_format.py): tabular IO · Delimited text import/export · `annnet/io/csv_format.py`
- [SBML](https://github.com/saezlab/annnet/blob/main/annnet/io/sbml.py): domain IO · SBML import/export and COBRA variant support · `annnet/io/sbml.py`
- [SIF](https://github.com/saezlab/annnet/blob/main/annnet/io/sif.py): domain IO · Simple interaction format support · `annnet/io/sif.py`

### Support

Shared backend-agnostic utilities

- [Dataframes](https://github.com/saezlab/annnet/blob/main/annnet/_support/dataframe_backend.py): compat layer · Narwhals-based dataframe backend abstraction · `annnet/_support/dataframe_backend.py`
- [Metadata](https://github.com/saezlab/annnet/blob/main/annnet/_support/metadata.py): utilities · Metadata helpers and serialization support · `annnet/_support/metadata.py`
- [Optional deps](https://github.com/saezlab/annnet/blob/main/annnet/_support/optional_components.py): utilities · Optional component gating and lazy imports · `annnet/_support/optional_components.py`
- [Plotting](https://github.com/saezlab/annnet/blob/main/annnet/utils/plotting.py): utilities · Backend-aware plotting integration · `annnet/utils/plotting.py`

### Algorithms

Graph-native routines built on the core model

- [Traversal](https://github.com/saezlab/annnet/blob/main/annnet/algorithms/traversal.py): algorithm · Graph-native traversal routines · `annnet/algorithms/traversal.py`

## Connections

- Graph → Matrix: stores topology · Graph orchestrates sparse structural state
- Graph → Layers: tracks layers · Layer semantics are managed as separate state
- Graph → Slices: tracks slices · Slice semantics are managed as separate state
- Graph → Annotations: stores metadata · Annotations live in dataframe-backed tables
- Graph → History: records changes · Mutation history is tracked separately from structure
- Graph → Views: exposes views · Derived and filtered projections sit on top of core state
- Graph → Ops: mutates via · Graph operations coordinate state transitions
- Graph → Records: uses records · Internal record helpers support core state handling
- Graph → NX Accessor: projected by · Graph-owned accessors lazily build backend graphs
- Graph → IG Accessor: projected by · Graph-owned accessors lazily build backend graphs
- Graph → GT Accessor: projected by · Graph-owned accessors lazily build backend graphs
- NX Accessor → NetworkX: converts to · NetworkX adapter performs interoperability conversion
- IG Accessor → igraph: converts to · igraph adapter performs interoperability conversion
- GT Accessor → graph-tool: converts to · graph-tool adapter performs interoperability conversion
- Graph → PyG: exports to · PyG interoperability is handled outside the core model
- Graph → .annnet: persists as · Native lossless storage format
- Graph → GraphML/GEXF: imports/exports · External interchange formats are handled in I/O
- Graph → JSON: imports/exports · JSON formats are handled in I/O
- Graph → Parquet: stores tables · Columnar storage supports annotations and indices
- Graph → CSV/TSV: imports/exports · Delimited formats are handled in I/O
- Graph → SBML: imports/exports · SBML family is handled in I/O
- Graph → SIF: imports/exports · SIF support is handled in I/O
- Dataframes → Annotations: backing tables · Table operations are backend-abstracted through Narwhals
- Metadata → .annnet: supports · Metadata helpers participate in persistence and manifests
- Optional deps → NX Accessor: gates · Optional dependency handling controls backend availability
- Optional deps → IG Accessor: gates · Optional dependency handling controls backend availability
- Optional deps → GT Accessor: gates · Optional dependency handling controls backend availability
- Optional deps → Plotting: gates · Optional dependency handling controls plotting integrations
- Plotting → Graph: visualizes · Plotting utilities render graph state
- Traversal → Graph: operates on · Algorithms target the AnnNet graph model directly
- Traversal → Views: uses projections · Algorithms can work on derived views and selections
